故障排除

pnpm 和 .npmrc 配置问题

shamefully-hoist 已移除

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

原因：shamefully-hoist 会将所有依赖提升到 node_modules 根目录，破坏了 pnpm 的严格依赖隔离机制。这可能导致：

• 意外访问未声明的依赖
• 依赖版本冲突
• 构建不稳定

迁移指南：

1. 删除项目中的 .npmrc 文件（如果存在）
2. 运行 pnpm install 重新安装依赖
3. 如遇到依赖找不到的错误，将缺失的包添加到 package.json 的 dependencies 中

Tailwind CSS 作为 Peer Dependency

Tailwind CSS 已从直接依赖改为 peerDependencies。这意味着：

主题使用者需要手动安装：

pnpm add -D tailwindcss

样式定制问题

自定义 CSS 配置

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

方法 1：使用 @nuxt/ui 的样式系统

需要先安装 @nuxt/ui：

pnpm add @nuxt/ui

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

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

方法 2：创建自定义 CSS 文件

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

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

依赖安装问题

Peer Dependencies 警告

安装时可能会看到以下警告：

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

解决方法：

pnpm add -D tailwindcss@^4.1.0

构建脚本审批

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

方法 1：交互式审批（推荐）

pnpm approve-builds

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

方法 2：配置文件方式

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

onlyBuiltDependencies:
  - '@swc/core'
  - better-sqlite3
  - sharp

或在 package.json 中：

{
  "pnpm": {
    "onlyBuiltDependencies": [
      "@swc/core",
      "better-sqlite3",
      "sharp"
    ]
  }
}

Vercel 部署问题

Node 版本支持

本项目同时支持 Node.js 22 LTS 和 Node.js 24。

历史问题（已修复）：

早期版本在 Node 24 环境下可能遇到以下错误：

[vite:wasm-fallback] Could not load onig.wasm (imported by shiki):
"ESM integration proposal for Wasm" is not supported currently

此问题已通过内置的 WASM 配置解决，无需手动处理。

WASM 和 Shiki 配置

本项目使用 Shiki 进行语法高亮，需要 WASM 支持。相关配置已内置在 layer/nuxt.config.ts 中：

// 已内置配置，无需手动添加
hooks: {
  'vite:extendConfig': async (config) => {
    // WASM 插件支持
    const [wasm, topLevelAwait] = await Promise.all([
      import('vite-plugin-wasm'),
      import('vite-plugin-top-level-await')
    ])
    config.plugins.push(wasm.default(), topLevelAwait.default())

    // 配置 WASM 运行时导入为外部依赖
    config.build.rollupOptions.external = [
      ...existing,
      'env',
      'wasi_snapshot_preview1'
    ]
  }
}

Output Directory 找不到

错误信息：

Error: No Output Directory named "dist" found after the Build completed.
Configure the Output Directory in your Project Settings.

解决方法：

在 Vercel 项目设置中配置：

1. 进入 Settings → General → Build & Development Settings
2. 设置 Output Directory：

docs/.output/public

或在 vercel.json 中配置：

{
  "buildCommand": "pnpm build",
  "outputDirectory": "docs/.output/public"
}