构建报错「已启用的功能缺少依赖」
[@movk/nuxt-docs] 已启用的功能缺少依赖:
- mermaid: mermaid, dompurify
请安装后重试:pnpm add mermaid dompurify
AI Chat、组件文档、Mermaid 与 a11y 默认关闭,它们的依赖是 Layer 的可选 peer 依赖,不会自动安装。打开对应开关后,Layer 在构建开始前检查依赖,缺少时中止构建并给出安装命令。执行报错中的命令即可,各功能所需的包见功能开关:
| 功能 | 需要安装的包 |
|---|---|
| AI Chat | ai @ai-sdk/openai @ai-sdk/vue @comark/vue @shikijs/engine-javascript @shikijs/langs @shikijs/themes |
| 组件文档 | nuxt-component-meta vue-component-meta prettier |
| Mermaid | mermaid dompurify |
| a11y | @nuxt/a11y |
AI Chat 在构建环境存在 AI_API_KEY 时自动启用,所以 CI 中配置了这个变量,就需要安装 AI Chat 的依赖;不需要时设置 aiChat.enabled: false。
构建报错「aiChat 依赖 MCP Server」
[@movk/nuxt-docs] aiChat 依赖 MCP Server,请勿在启用 aiChat 时设置 movkNuxtDocs.mcp: false
AI Chat 通过站点自身的 MCP Server 检索文档,两者不能拆开。保留 MCP,或同时关闭 AI Chat:
export default defineNuxtConfig({
aiChat: {
enabled: false
},
movkNuxtDocs: {
mcp: false
}
})
文档页面全部 404
构建时出现以下警告,说明 Layer 没有找到文档目录:
[@movk/nuxt-docs] 未找到 content/docs 目录,文档页面固定位于 /docs 下,请将文档放入 content/docs/
文档必须位于 content/docs/,路由前缀固定为 /docs;多语言站点中其他语言放在 content/{code}/docs/。把文档移入该目录即可,文件名前的数字前缀只用于排序,不出现在 URL 中。目录约定见项目结构。
启用多语言后构建失败
i18n.locales 中声明了 file 时,@nuxtjs/i18n 会去站点自己的 i18n/locales/ 目录查找翻译文件,找不到就会构建失败。去掉 file,只保留 code 与 name:
export default defineNuxtConfig({
i18n: {
defaultLocale: 'zh-CN',
locales: [
{ code: 'zh-CN', name: '简体中文' },
{ code: 'en', name: 'English' }
]
}
})
某种语言没有生效
构建日志中出现「缺少翻译文件」或「缺少内容目录」的告警时,该语言已被跳过:
[movk-docs] 缺少内容目录 content/en/,已跳过 locale "en"
非默认语言需要同时具备 Layer 内置的翻译文件(目前为 zh-CN 与 en)和 content/{code}/ 目录,见国际化。
pnpm 安装后图片处理失败
pnpm 默认不运行依赖的安装脚本,@nuxt/image 使用的 sharp 需要显式允许。在项目根目录的 pnpm-workspace.yaml 中声明:
allowBuilds:
sharp: true
也可以运行 pnpm approve-builds 交互式选择。修改后重新执行 pnpm install。官方模板已包含这项配置。
缺少 peer 依赖 tailwindcss
WARN Issues with peer dependencies found
└─┬ @movk/nuxt-docs
└── ✕ missing peer tailwindcss@4.x
nuxt、@nuxt/content 与 tailwindcss 是必需的 peer 依赖,需要在项目中安装:
pnpm add nuxt @nuxt/content tailwindcss
npm install nuxt @nuxt/content tailwindcss
yarn add nuxt @nuxt/content tailwindcss
bun add nuxt @nuxt/content tailwindcss
提交记录与最后更新时间不显示
CommitChangelog 与 PageLastCommit 在浏览器中请求 GitHub 数据,依次检查:
- 运行环境是否设置了
NUXT_GITHUB_TOKEN。没有令牌时接口直接返回空结果; app.config的github.owner、github.name、github.branch是否与仓库一致。未设置时 Layer 会从 Git 信息推断,推断失败就没有数据;- 文档不在仓库根目录时,
github.rootDir是否指向文档所在目录; - 站点是否以纯静态方式部署。静态站点没有
/api/github/*接口,见部署。
AI Chat 没有出现
AI Chat 是否打包在构建时决定:构建环境需要存在 AI_API_KEY,或在 nuxt.config.ts 中设置 aiChat.enabled: true。只在运行环境配置变量不会让已构建的站点出现 AI Chat,配置后需要重新构建。详见 AI Chat。
Google Fonts 请求失败
Could not fetch from https://fonts.google.com/metadata/fonts. Will retry in 1000ms. 3 retries left.
Layer 默认设置 ui.fonts: false,并自托管 Inter、Fraunces 与 JetBrains Mono,不会请求 Google Fonts。出现这条警告说明项目中重新开启了 @nuxt/fonts,关闭即可:
export default defineNuxtConfig({
ui: {
fonts: false
}
})
需要中文字体时的引入方法见主题与字体。