构建失败

常见错误及修复

1. Duplicate export of 'default'

原因：src/pages/index.js 中有两个 export default（之前写入文件时意外追加）。

解决：检查 index.js，确保只有一个 export default function Home()。

2. require.resolve is not defined (ESM)

原因：docusaurus.config.js 使用 export default（ESM 模式），不支持 require.resolve。

解决：使用 ES import 语法：

import searchLocal from '@easyops-cn/docusaurus-search-local';

3. onBrokenMarkdownLinks 警告

原因：Docusaurus v3 中 siteConfig.onBrokenMarkdownLinks 已废弃。

解决：迁移到新位置（可选，不影响构建）：

// 旧配置
onBrokenMarkdownLinks: 'warn',

// 新配置
markdown: {
  hooks: {
    onBrokenMarkdownLinks: 'warn',
  },
},

4. 端口被占用

现象：EADDRINUSE: address already in use :::3000

解决：

# Windows
Get-Process -Name node -ErrorAction SilentlyContinue | Stop-Process -Force

# 然后重新启动
npm run serve -- --port 3000

5. 缓存导致构建异常

解决：

npm run clear
npm run build

构建流程检查清单

1. npm run build 是否成功（无 ERROR）
2. build/ 目录是否生成
3. build/config.yml 是否存在（CMS 需要）
4. npm run serve -- --port 3000 是否正常访问
5. 搜索功能是否可用（验证 build 索引生成）