Vuepress构建报错：TypeError: Cannot read properties of undefined (reading 'match')

问题描述 #

按Vuepress官方手动安装流程用npm搭建项目，添加页面后npm run dev运行正常，但执行npm run build时出现报错，核心错误信息如下：

[vuepress] No matching page found for sidebar item "/index"
[Vue warn]: Error in render: "TypeError: Cannot read properties of undefined (reading 'match')"
[vuepress] No matching page found for sidebar item "/elements/attribute"
TypeError: Cannot read properties of undefined (reading 'match')
    at getHash (node_modules/@vuepress/theme-default/util/index.js:13:21)

解决步骤 #

• 检查侧边栏配置的页面路径
  确认.vuepress/config.js里侧边栏配置的路径与实际文件路径完全匹配：
  • 侧边栏中/index对应的文件应为src/index.md，若首页文件存在，可尝试将路径改为/；
  • /elements/attribute对应的文件应为src/elements/attribute.md，检查文件是否存在、路径拼写是否正确，注意大小写敏感（开发环境可能忽略大小写，但构建时严格校验）。
• 修正侧边栏路径格式
  确保侧边栏项的路径符合Vuepress路由规则：
  • 根页面使用/而非/index；
  • 子页面使用/elements/attribute（对应src/elements/attribute.md）或/elements/attribute/（对应src/elements/attribute/index.md）。
• 清理构建缓存
  删除缓存目录后重新构建：

  # Linux/macOS
  rm -rf node_modules/.cache
  # Windows
  rmdir /s node_modules\.cache
  npm run build
  

• 验证文件结构
  确认项目文件结构与预期一致，示例结构：

  docs/
  ├─ src/
  │  ├─ index.md
  │  ├─ elements/
  │  │  └─ attribute.md
  └─ .vuepress/
     └─ config.js
  

内容的提问来源于stack exchange，提问作者JInsider