VitePress 构建问题汇总

本文汇总 VitePress 构建过程中遇到的两个典型问题及其解决方案。

问题一：死链接检测

错误信息

(!) Found dead link http://localhost:5174 in file posts/playwright-test-plan.md
[vitepress] 1 dead link(s) found.

原因

VitePress 构建时会检测所有链接有效性，http://localhost:5174 在构建环境下无法访问，被识别为死链接。

解决方案

方案 1：忽略死链接（在 .vitepress/config.mts 中配置）

export default defineConfig({
  markdown: {
    ignoreDeadLinks: true
  }
})

方案 2：修改为纯文本描述

- 开发服务器运行在 http://localhost:5174
+ 开发服务器运行在本地 5174 端口

问题二：Vue 模板语法冲突

错误信息

Cannot read properties of undefined (reading 'XXX')
TypeError: Cannot read properties of undefined (reading 'XXX')
    at _sfc_ssrRender

原因

VitePress 使用 Vue 作为渲染引擎，文档中的双大括号被误解析为 Vue 模板语法。

解决方案

修改为纯文本描述：

- 使用 `secrets.XXX` 占位符
+ 使用 secrets.XXX 占位符

问题三：Frontmatter 格式错误

错误信息

[vitepress] end of the stream or a document separator is expected at line 9

原因

frontmatter 中存在空行或格式不规范：

---
draft: true    # 这里是空行，导致解析失败
---

解决方案

移除无效的 frontmatter 或确保格式正确：

---
draft: true
---
# 标题直接跟在闭合格式符后面

经验总结

问题类型	触发原因	预防措施
死链接	本地开发环境链接	避免在文档中使用 localhost 链接
Vue 语法冲突	双大括号	避免在文档中使用双大括号
Frontmatter 错误	格式不规范	使用标准 YAML 格式

相关配置

项目中已添加忽略死链接配置（可选）：

// docs/.vitepress/config.mts
export default defineConfig({
  markdown: {
    ignoreDeadLinks: true
  }
})