---
title: "故障排查"
description: "汇总可选依赖缺失、AI Chat 与 MCP 依赖关系、文档 404、多语言配置、pnpm 构建脚本审批与提交记录问题的解决办法。"
canonical_url: "https://docs.mhaibaraai.cn/docs/guide/troubleshooting"
---
# 故障排查

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

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

```text [terminal]
[@movk/nuxt-docs] 已启用的功能缺少依赖：
  - mermaid: mermaid, dompurify
请安装后重试：pnpm add mermaid dompurify
```

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

| 功能 | 需要安装的包 |
| --- | --- |
| 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」

```text [terminal]
[@movk/nuxt-docs] aiChat 依赖 MCP Server，请勿在启用 aiChat 时设置 movkNuxtDocs.mcp: false
```

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

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

## 文档页面全部 404

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

```text [terminal]
[@movk/nuxt-docs] 未找到 content/docs 目录，文档页面固定位于 /docs 下，请将文档放入 content/docs/
```

文档必须位于 `content/docs/`，路由前缀固定为 `/docs`；多语言站点中其他语言放在 `content/{code}/docs/`。把文档移入该目录即可，文件名前的数字前缀只用于排序，不出现在 URL 中。目录约定见[项目结构](https://docs.mhaibaraai.cn/docs/getting-started/project-structure)。

## 启用多语言后构建失败

`i18n.locales` 中声明了 `file` 时，`@nuxtjs/i18n` 会去站点自己的 `i18n/locales/` 目录查找翻译文件，找不到就会构建失败。去掉 `file`，只保留 `code` 与 `name`：

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

## 某种语言没有生效

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

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

非默认语言需要同时具备 Layer 内置的翻译文件（目前为 `zh-CN` 与 `en`）和 `content/{code}/` 目录，见[国际化](https://docs.mhaibaraai.cn/docs/guide/i18n#%E8%AF%AD%E8%A8%80%E7%9A%84%E6%9C%89%E6%95%88%E6%9D%A1%E4%BB%B6)。

## pnpm 安装后图片处理失败

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

```yaml [pnpm-workspace.yaml]
allowBuilds:
  sharp: true
```

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

> [!NOTE]
> 
> pnpm 11 起构建审批统一使用 
> 
> allowBuilds
> 
> ，
> 
> onlyBuiltDependencies
> 
>  等旧设置已移除。见 
> 
> pnpm 文档
> 
> 。

## 缺少 peer 依赖 tailwindcss

```text [terminal]
WARN  Issues with peer dependencies found
└─┬ @movk/nuxt-docs
  └── ✕ missing peer tailwindcss@4.x
```

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

```bash [pnpm]
pnpm add nuxt @nuxt/content tailwindcss
```

```bash [npm]
npm install nuxt @nuxt/content tailwindcss
```

```bash [yarn]
yarn add nuxt @nuxt/content tailwindcss
```

```bash [bun]
bun add nuxt @nuxt/content tailwindcss
```

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

[`CommitChangelog`](https://docs.mhaibaraai.cn/docs/components/commit-changelog) 与 [`PageLastCommit`](https://docs.mhaibaraai.cn/docs/components/page-last-commit) 在浏览器中请求 GitHub 数据，依次检查：

1. 运行环境是否设置了 `NUXT_GITHUB_TOKEN`。没有令牌时接口直接返回空结果；
2. `app.config` 的 `github.owner`、`github.name`、`github.branch` 是否与仓库一致。未设置时 Layer 会从 Git 信息推断，推断失败就没有数据；
3. 文档不在仓库根目录时，`github.rootDir` 是否指向文档所在目录；
4. 站点是否以纯静态方式部署。静态站点没有 `/api/github/*` 接口，见[部署](https://docs.mhaibaraai.cn/docs/guide/deployment#%E9%9D%99%E6%80%81%E7%94%9F%E6%88%90)。

## AI Chat 没有出现

AI Chat 是否打包在**构建时**决定：构建环境需要存在 `AI_API_KEY`，或在 `nuxt.config.ts` 中设置 `aiChat.enabled: true`。只在运行环境配置变量不会让已构建的站点出现 AI Chat，配置后需要重新构建。详见 [AI Chat](https://docs.mhaibaraai.cn/docs/ai/ai-chat)。

## Google Fonts 请求失败

```text [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`，关闭即可：

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

需要中文字体时的引入方法见[主题与字体](https://docs.mhaibaraai.cn/docs/guide/theme)。


## Sitemap

See the full [sitemap](https://docs.mhaibaraai.cn/sitemap.md) for all pages.
