Fumadocs/Next.js 内容页面不显示问题排查总结

Fumadocs/Next.js 内容页面不显示问题排查总结

一、 问题描述 (Problem)

现象 (Symptom)

• 单个文档页面 (analysis-framework-guide.mdx) 无法在网站上正常访问和显示。
• 直接访问该页面 URL 可能会看到 404 错误或构建错误页面。

根本原因 (Root Cause)

• 整个 Next.js 项目构建失败。失败的原因并非出在无法显示的 analysis-framework-guide.mdx 文件本身，而是由另一个不相关的 qwen3.mdx 文件中的一个微小语法错误导致的。
• 错误详情: qwen3.mdx 文件头部的元数据 (Frontmatter) 中存在一个不符合 YAML 语法的缩进错误，导致 MDX 内容解析器在构建时崩溃，从而使整个网站无法成功生成。

---

二、 修复方法 (Fix Process)

1. 诊断 (Diagnosis):

   • 启动开发服务器并查看日志。这是最关键的一步。通过在项目根目录运行 npm run dev，可以直接在终端或日志文件中看到 Next.js 的实时构建错误信息。
   • 命令:

     npm run dev

2. 定位 (Identification):

   • 仔细阅读错误日志。错误信息 YAMLException: bad indentation of a mapping entry at line 3, column 3 准确地指出了：
     • 错误类型: YAMLException (YAML 语法错误)
     • 错误文件: ./content/docs/thoughts/qwen3.mdx
     • 错误位置: line 3, column 3 (第三行第三列)

3. 修复 (Resolution):

   • 修正 YAML 语法。打开 qwen3.mdx 文件，根据错误提示，删除或修正第三行 Qwen3: 心性 的多余缩进。
   • 操作: 使用代码编辑器的替换功能或手动编辑文件，移除导致错误的代码行。

4. 验证 (Verification):

   • 清除缓存并重启服务。为确保修改生效且不受旧缓存影响，推荐在修复后执行以下操作：
     1. 删除 .next 缓存目录。
     2. 重启开发服务器 (npm run dev)。
   • 检查页面: 重新访问之前无法显示的页面和被修改的页面，确认它们都已恢复正常。

---

三、 核心教训 (Key Takeaway)

• 一个文件的错误可能导致整个站点瘫痪。在 Next.js 或类似框架中，构建过程是整体性的。任何一个页面或组件的严重错误都可能导致所有页面都无法正常显示。
• 问题页面不一定是错误根源。当某个页面无法显示时，不要只检查该文件本身。真正的错误可能隐藏在最近修改过的任何其他文件中。
• 开发服务器日志是你的“侦探”。解决构建问题的最快途径几乎总是启动开发服务器 (npm run dev) 并仔细阅读它提供的错误报告。日志会明确告诉你哪个文件、哪一行代码出了问题。