故障排除

查看源码

解决使用 Movk Nuxt Docs 时遇到的常见问题，包括 Google Fonts 访问、pnpm shamefully-hoist 配置移除、Tailwind CSS peer dependency 安装、构建脚本审批，以及 Vercel 部署 OOM 内存不足等问题的详细解决方案。

字体加载问题

Google Fonts 在大陆环境下无法访问

@nuxt/fonts 模块默认从 fonts.google.com 拉取字体元数据。在无法访问 Google 的网络环境下，开发服务器启动时会出现以下警告：

terminal

Could not fetch from https://fonts.google.com/metadata/fonts. Will retry in 1000ms. 3 retries left.

修复方式：将字体 provider 改为 bunny（隐私友好的 Google Fonts 兼容替代品）：

nuxt.config.ts

export default defineNuxtConfig({
  fonts: {
    families: [
      { name: 'Public Sans', global: true, provider: 'bunny' }
    ]
  }
})

@nuxt/fonts 支持多个字体 provider，详见官方文档。

pnpm 和 .npmrc 配置问题

shamefully-hoist 已移除

从 v1.10.0 版本开始，项目已移除 .npmrc 中的 shamefully-hoist=true 配置。

shamefully-hoist 会将所有依赖提升到 node_modules 根目录，破坏 pnpm 的严格依赖隔离机制，可能导致意外访问未声明的依赖、版本冲突和构建不稳定。

删除 `.npmrc`

删除项目中的 .npmrc 文件（如果存在）。

重新安装依赖

pnpm install

补齐缺失的依赖

如遇到依赖找不到的错误，将缺失的包添加到 package.json 的 dependencies 中。

参考 pnpm 官方文档了解更多关于 shamefully-hoist 的信息

Tailwind CSS 作为 Peer Dependency

Tailwind CSS 已从直接依赖改为 peerDependencies，主题使用者需要手动安装：

pnpm add -D tailwindcss

样式定制问题

自定义 CSS 配置

~~从 v1.10.0 开始，app/assets/css/main.css 不再是必需的~~。如果你需要自定义样式：

需要先安装 @nuxt/ui：

pnpm add @nuxt/ui

然后在 nuxt.config.ts 中配置：

nuxt.config.ts

export default defineNuxtConfig({
  modules: ['@nuxt/ui'],
  ui: {
    // 自定义主题配置
  }
})

在 app/assets/css/main.css 中添加全局样式，并在 nuxt.config.ts 中引入：

nuxt.config.ts

export default defineNuxtConfig({
  css: ['~/assets/css/main.css']
})

依赖安装问题

Peer Dependencies 警告

安装缺失的 peer dependency 即可解决：

pnpm add -D tailwindcss@^4.1.0

构建脚本审批

从 pnpm v10 开始，默认情况下不会运行依赖的 lifecycle scripts（如 postinstall）。本项目需要审批以下包含原生模块的依赖：

依赖包	用途	是否必需
`better-sqlite3`	SQLite 数据库（用于 MCP 服务器）	是
`sharp`	图片处理（用于 @nuxt/image）	是

pnpm approve-builds

从列表中选择上述包进行审批。

在项目根目录的 pnpm-workspace.yaml 中添加：

pnpm-workspace.yaml

onlyBuiltDependencies:
  - better-sqlite3
  - sharp

在 package.json 中添加：

package.json

{
  "pnpm": {
    "onlyBuiltDependencies": [
      "better-sqlite3",
      "sharp"
    ]
  }
}

这些配置仅影响开发环境。发布的包不会传递此配置，消费者需要自行配置。

了解更多关于构建脚本审批的信息

Nitro 预渲染问题

unist-util-visit 包找不到

@nuxt/content 的 LLMs 集成在 Nitro 预渲染 /llms-full.txt 时，通过 import("unist-util-visit") 动态导入该包。pnpm 的严格依赖隔离使得 Nitro 输出目录（docs/node_modules/.cache/）无法解析到仅存在于 layer 依赖链中的包。

在消费方项目的 package.json 中显式声明缺失的运行时依赖：

package.json

{
  "dependencies": {
    "unist-util-visit": "^5.1.0",
    "@nuxtjs/mdc": "^0.20.1"
  }
}

使用 .npmrc 将特定包提升到根目录：

.npmrc

public-hoist-pattern[]=unist-util-visit
public-hoist-pattern[]=@nuxtjs/mdc

添加后运行 pnpm install 使配置生效。

Vercel 部署问题

Output Directory 找不到

此错误通常不是输出目录配置问题。Nuxt 使用 vercel preset 构建时，Nitro 会自动生成 .vercel/output/ 目录（Vercel Build Output API 格式），Vercel 能自动识别该目录，无需手动配置 outputDirectory。

出现此错误的最常见原因是构建过程中内存不足（OOM），导致 .vercel/output/ 未完整生成，Vercel 回退查找默认的 dist 目录。

可以在 Vercel 构建日志末尾确认是否为 OOM：

FATAL ERROR: Ineffective mark-compacts near heap limit Allocation failed - JavaScript heap out of memory

或：

At least one "Out of Memory" ("OOM") event was detected during the build.

在 vercel.json 中通过 buildCommand 增大 Node.js 堆内存限制：

vercel.json

{
  "buildCommand": "NODE_OPTIONS='--max-old-space-size=7168' pnpm run build",
  "framework": null,
  "installCommand": "pnpm install --frozen-lockfile"
}

Vercel Hobby 计划的构建容器为 8 GB 内存，Node.js 默认堆限制约 4 GB。设置 --max-old-space-size=7168（7 GB）可为 Nitro 构建和预渲染提供充足的内存空间。

如果增大内存后仍然 OOM，可以考虑：

升级到 Vercel Pro 计划以获得更大的构建容器
减少预渲染路由数量

国际化

Movk Nuxt Docs 内置基于 @nuxtjs/i18n 的多语言能力，采用 opt-in 设计：未配置时按单语言运行，配置后自动启用多语言路由、内容集合、语言切换器与多语言 SEO。本页介绍单语言界面配置、多语言站点搭建、内容目录约定与翻译文件管理。

配置文档站点

通过 app.config.ts 自定义 SEO 元数据、头部导航、页脚版权、侧边栏导航过滤和 AI Chat 界面，通过 nuxt.config.ts 配置 GitHub 集成、组件元数据生成、Mermaid 图表和无障碍功能等模块级选项的完整参考。