故障排查

汇总可选依赖缺失、AI Chat 与 MCP 依赖关系、文档 404、多语言配置、pnpm 构建脚本审批与提交记录问题的解决办法。
查看源码

构建报错「已启用的功能缺少依赖」

AI Chat、组件文档、Mermaid 与 a11y 默认关闭,它们的依赖是 Layer 的可选 peer 依赖,不会自动安装。打开对应开关后,Layer 在构建开始前检查依赖,缺少时中止构建并给出安装命令。执行报错中的命令即可,各功能所需的包见功能开关:

功能需要安装的包
AI Chatai @ai-sdk/openai @ai-sdk/vue @comark/vue @shikijs/engine-javascript @shikijs/langs @shikijs/themes
组件文档nuxt-component-meta vue-component-meta prettier
Mermaidmermaid dompurify
a11y@nuxt/a11y

AI Chat 在构建环境存在 AI_API_KEY 时自动启用,所以 CI 中配置了这个变量,就需要安装 AI Chat 的依赖;不需要时设置 aiChat.enabled: false。

构建报错「aiChat 依赖 MCP Server」

AI Chat 通过站点自身的 MCP Server 检索文档,两者不能拆开。保留 MCP,或同时关闭 AI Chat:

nuxt.config.ts
export default defineNuxtConfig({
  aiChat: {
    enabled: false
  },
  movkNuxtDocs: {
    mcp: false
  }
})

文档页面全部 404

构建时出现以下警告,说明 Layer 没有找到文档目录:

terminal
[@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:

nuxt.config.ts
export default defineNuxtConfig({
  i18n: {
    defaultLocale: 'zh-CN',
    locales: [
      { code: 'zh-CN', name: '简体中文' },
      { code: 'en', name: 'English' }
    ]
  }
})

某种语言没有生效

构建日志中出现「缺少翻译文件」或「缺少内容目录」的告警时,该语言已被跳过:

terminal
[movk-docs] 缺少内容目录 content/en/,已跳过 locale "en"

非默认语言需要同时具备 Layer 内置的翻译文件(目前为 zh-CN 与 en)和 content/{code}/ 目录,见国际化。

pnpm 安装后图片处理失败

pnpm 默认不运行依赖的安装脚本,@nuxt/image 使用的 sharp 需要显式允许。在项目根目录的 pnpm-workspace.yaml 中声明:

pnpm-workspace.yaml
allowBuilds:
  sharp: true

也可以运行 pnpm approve-builds 交互式选择。修改后重新执行 pnpm install。官方模板已包含这项配置。

pnpm 11 起构建审批统一使用 allowBuilds,onlyBuiltDependencies 等旧设置已移除。见 pnpm 文档。

缺少 peer 依赖 tailwindcss

nuxt、@nuxt/content 与 tailwindcss 是必需的 peer 依赖,需要在项目中安装:

pnpm add nuxt @nuxt/content tailwindcss

提交记录与最后更新时间不显示

CommitChangelog 与 PageLastCommit 在浏览器中请求 GitHub 数据,依次检查:

  1. 运行环境是否设置了 NUXT_GITHUB_TOKEN。没有令牌时接口直接返回空结果;
  2. app.config 的 github.owner、github.name、github.branch 是否与仓库一致。未设置时 Layer 会从 Git 信息推断,推断失败就没有数据;
  3. 文档不在仓库根目录时,github.rootDir 是否指向文档所在目录;
  4. 站点是否以纯静态方式部署。静态站点没有 /api/github/* 接口,见部署。

AI Chat 没有出现

AI Chat 是否打包在构建时决定:构建环境需要存在 AI_API_KEY,或在 nuxt.config.ts 中设置 aiChat.enabled: true。只在运行环境配置变量不会让已构建的站点出现 AI Chat,配置后需要重新构建。详见 AI Chat。

Google Fonts 请求失败

terminal
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,关闭即可:

nuxt.config.ts
export default defineNuxtConfig({
  ui: {
    fonts: false
  }
})

需要中文字体时的引入方法见主题与字体。

Copyright © 2024 - 2026