常见问题

关于 Movk Nuxt Docs 的常见疑问:与 Nuxt UI 文档模板的关系、包管理器与 Node.js 版本、单语言站点、关闭 GitHub 集成、接入其他 AI 厂商、升级与组件覆盖、静态部署的限制等,每条都链接到详细说明。
查看源码

它和 Nuxt UI 的文档模板是什么关系?

Movk Nuxt Docs 源自 Nuxt UI 的文档站点与 UI 文档模板,以 Nuxt Layer 的形式发布为 @movk/nuxt-docs。在此基础上增加了组件文档自动生成、AI Chat、MCP Server、Agent Skills、多语言与编辑风主题,并定期同步上游的改动。你只需在 nuxt.config.ts 中 extends: ['@movk/nuxt-docs'],不必复制模板代码。见简介。

必须使用 pnpm 吗?

不必,pnpm、npm、yarn 与 bun 都可以。环境要求是 Nuxt 4.6.1+(4.x),以及 Node.js 22.22.3+(22.x)、24.15.0+(24.x)或 26+。Nuxt Content 依赖内置的 node:sqlite。使用 pnpm 时需要在 pnpm-workspace.yaml 中允许 sharp 的构建脚本,见故障排查。

不需要多语言,可以不装 @nuxtjs/i18n 吗?

可以,这是默认状态。不配置 i18n 时站点按单语言运行,URL 不带语言前缀;界面文案的语言用 app.config 的 i18n.locale 切换。见国际化。

文档必须放在 content/docs 吗?

是的。文档固定位于 content/docs/,路由前缀固定为 /docs,其他语言放在 content/{code}/docs/。首页来自 content/index.md,存在 app/pages/index.vue 时改用你自己的页面。见项目结构。

如何关闭 GitHub 集成?

在 app.config.ts 中把 github 设为 false,编辑链接、查看源码与提交记录都会隐藏:

app/app.config.ts
export default defineAppConfig({
  github: false
})

保留集成时,Layer 会从 Git 信息推断仓库,生产环境需要配置 NUXT_GITHUB_TOKEN。见配置。

能用 OpenAI 以外的模型厂商吗?

能。设置 AI_BASE_URL 即可直连任意 OpenAI 兼容端点(如 DeepSeek、通义千问);不设置时通过 Vercel AI Gateway 调用 provider/model 形式的模型。需要接入不兼容 OpenAI 协议的厂商时,在 server/plugins/ 中用 modelProviderRegistry.register() 注册对应的 AI SDK provider。见 AI Chat。

不想启用 AI Chat 怎么办?

不配置 AI_API_KEY 即可,AI Chat 默认不启用,相关依赖也不会打包。构建环境中存在 AI_API_KEY 但不需要 AI Chat 时,设置 aiChat.enabled: false。见功能开关。

如何升级 Layer?

升级 @movk/nuxt-docs 的版本后重新安装依赖:

pnpm add @movk/nuxt-docs@latest

从 v2 升级到 v3 时,先阅读迁移指南,其中列出了全部破坏性变更。每个版本的改动见版本发布。

如何修改页头、页脚等界面组件?

在项目的 app/components/ 中创建同名组件即可覆盖 Layer 的实现,例如 app/components/HeaderLogo.vue。只有覆盖契约中列出的组件承诺在 v3.x 内保持名称、挂载位置与 props 稳定,未列出的组件属于内部实现。只想调整导航链接时,优先使用 app.config 的 header.nav,见导航与分类。

如何更换主色或字体?

默认主色为 vermilion(朱红),中性色为 paper(暖灰),标题使用衬线字体。主色通过 app.config 的 ui.colors 修改,标题字体通过 theme.font 切换为全站无衬线。见主题与字体。

可以部署成纯静态站点吗?

可以,运行 nuxt generate 后把 .output/public/ 部署到任意静态托管。页面、搜索、组件文档与 OG 图片都正常工作,但 AI Chat、MCP Server、提交记录和 Markdown 内容协商依赖服务端,静态站点中不可用。见部署。

AI 代理如何读取我的文档?

Layer 默认提供 llms.txt、MCP Server 与 Markdown 内容协商:代理请求页面时可直接拿到 Markdown,/raw/**.md 提供每页的 Markdown 版本。见 llms.txt、MCP Server 与代理发现。

构建很慢或内存不足怎么办?

关闭不需要的功能能明显减少构建开销,例如 movkNuxtDocs.ogImage: false 跳过每页的 OG 图片渲染。

Copyright © 2024 - 2026