---
title: "故障排除"
description: "解决使用 Movk Nuxt Docs 时遇到的常见问题，包括 Google Fonts 访问、pnpm shamefully-hoist 配置移除、Tailwind CSS peer dependency 安装、构建脚本审批，以及 Vercel 部署 OOM 内存不足等问题的详细解决方案。"
seo_title: "Troubleshooting"
seo_description: "Fix common Movk Nuxt Docs issues with fonts, package manager settings, Tailwind CSS peer dependencies, build approvals, and Vercel memory limits."
canonical_url: "https://docs.mhaibaraai.cn/docs/getting-started/troubleshooting"
---
# 故障排除

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

## 字体加载问题

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

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

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

本主题已默认设置 `ui.fonts: false` 关闭该模块，正常情况下不会遇到这条警告。若你在自己的 `nuxt.config.ts` 中重新打开了它，把它关回去即可：

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

字体改由 `app/assets/css/main.css` 的 `@theme` 声明 `--font-sans`，样式表则在 `nuxt.config.ts` 的 `app.head.link` 中静态引入，全部随 SSR 直出。

> \[\!WARNING\]
> 
> 中文字体经 
> 
> unicode-range
> 
>  分包，一个家族动辄数百个分片。不要把它们交给 
> 
> @nuxt/fonts
> 
> ——它会在构建期把全部分片下载进产物，既失去按需加载，也丢掉跨项目共享的 CDN 缓存。

## pnpm 和 .npmrc 配置问题

### shamefully-hoist 已移除

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

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

#### 删除 `.npmrc`

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

#### 重新安装依赖

```bash
pnpm install
```

#### 补齐缺失的依赖

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

> \[\!WARNING\]
> See: https://pnpm.io/zh/npmrc#shamefully-hoist
> 
> 参考 pnpm 官方文档了解更多关于 
> 
> shamefully-hoist
> 
>  的信息

### Tailwind CSS 作为 Peer Dependency

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

```bash
pnpm add -D tailwindcss
```

## 样式定制问题

### 自定义 CSS 配置

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

需要先安装 `@nuxt/ui`：

```bash
pnpm add @nuxt/ui
```

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

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

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

```typescript [nuxt.config.ts]
export default defineNuxtConfig({
  css: ['~/assets/css/main.css']
})
```

## 依赖安装问题

### Peer Dependencies 警告

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

> \[\!TIP\]
> 
> 安装缺失的 peer dependency 即可解决：
> 
> ```bash
> pnpm add -D tailwindcss@^4.1.0
> ```

### 构建脚本审批

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

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

```bash
pnpm approve-builds
```

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

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

```yaml [pnpm-workspace.yaml]
onlyBuiltDependencies:
  - better-sqlite3
  - sharp
```

在 `package.json` 中添加：

```json [package.json]
{
  "pnpm": {
    "onlyBuiltDependencies": [
      "better-sqlite3",
      "sharp"
    ]
  }
}
```

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

> \[\!WARNING\]
> See: https://pnpm.io/zh/settings#onlybuiltdependencies
> 
> 了解更多关于构建脚本审批的信息

## Nitro 预渲染问题

### unist-util-visit 包找不到

```text
Cannot find package 'unist-util-visit' imported from .../prerender/chunks/nitro/nitro.mjs
Did you mean to import "unist-util-visit/index.js"?
```

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

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

```json [package.json]
{
  "dependencies": {
    "unist-util-visit": "^5.1.0",
    "@nuxtjs/mdc": "^0.20.1"
  }
}
```

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

```text [.npmrc]
public-hoist-pattern[]=unist-util-visit
public-hoist-pattern[]=@nuxtjs/mdc
```

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

## Vercel 部署问题

### Output Directory 找不到

```text
Error: No Output Directory named "dist" found after the Build completed.
```

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

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

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

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

或：

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

> \[\!TIP\]
> 
> 在 `vercel.json` 中通过 `buildCommand` 增大 Node.js 堆内存限制：
> 
> ```json [vercel.json]
> {
>   "buildCommand": "NODE_OPTIONS='--max-old-space-size=7168' pnpm run build",
>   "framework": null,
>   "installCommand": "pnpm install --frozen-lockfile"
> }
> ```

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

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

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


## Sitemap

See the full [sitemap](/sitemap.md) for all pages.