第 3 章
常见问题
汇总日常使用中的常见问题及解决方案，帮助你快速排查和修复错误。
本章汇总常见问题及解决方法。
内容问题
警注意
修改 frontmatter 后如果页面没有更新，请检查 slug 格式是否正确（小写字母、数字和连字符）。
构建问题
险构建失败
如果 npm run build 失败，请先运行校验命令排查：
bash运行内容校验
npm run check常见原因：
- 分类引用不存在
- slug 格式不正确
- 教程章节 order 重复
- 缺少必填字段
附件问题
如果附件下载链接失效，运行附件扫描脚本：
bash扫描附件
npm run assets:scan搜索问题
开发模式不生成搜索索引。要测试搜索功能：
- 运行
npm run build构建生产版本 - 使用
npm run preview在 4173 端口预览 - 或使用 Docker 在 8080 端口预览
注了解更多
查看项目文档了解更多细节：
docs/ARCHITECTURE.md— 架构说明docs/LOCAL_WORKFLOW.md— 日常工作流程docs/CONTENT_MODEL.md— 内容模型参考
获取帮助
如果你遇到本文未涵盖的问题，可以查看项目 README 或提交 Issue。