构建相关问题

dev 正常但 build 报错

为什么会这样？

模式	dev（开发）	build（构建）
链接检查	❌ 不检查	✅ 严格检查
加载方式	按需加载	预渲染所有页面
错误处理	宽松	严格，遇错即停

原因分析：

1. dev 模式（开发模式）

   • 不检查死链接
   • 只在你访问页面时才加载
   • 更宽松，为了开发体验
   • 即使链接错误，也能正常运行

2. build 模式（构建模式）

   • 会检查所有链接的有效性
   • 预渲染所有页面
   • 严格模式，确保生产环境没有问题
   • 发现死链接会直接报错并停止构建

配置选项：

// .vitepress/config.js
export default {
  ignoreDeadLinks: false  // 默认值，推荐保持
}

建议

不要设置 ignoreDeadLinks: true，而是修复所有死链接，确保用户体验。

注意事项：

• VitePress 只检查 Markdown 文件中的链接
• 配置文件（config.js）中的导航链接不会被检查
• 建议定期运行 build 命令验证链接有效性

死链接检查失败

常见原因：

1. 链接路径错误
2. 文件名大小写不匹配
3. 文件不存在或已删除
4. 使用了相对路径但层级错误

排查步骤：

1. 检查链接路径是否正确
2. 确认目标文件是否存在
3. 验证文件名大小写是否一致
4. 使用绝对路径（以 / 开头）更可靠

示例：

❌ 错误：[链接](../wrong/path.md)
✅ 正确：[链接](/web/vitepress/correct-path)