常见问题
它和 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,编辑链接、查看源码与提交记录都会隐藏:
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
npm install @movk/nuxt-docs@latest
yarn add @movk/nuxt-docs@latest
bun 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 图片渲染。