Hexo 404 及 Mermaid 图表渲染问题排查记录

发表于 分类于 ，

Hexo 404 及 Mermaid 图表渲染问题排查记录

作为 Hexo 用户，我最近也遇到了不少恼人的问题，特别是 Mermaid 图表无法渲染以及部署后出现 404 错误。这里记录一下整个排查和解决过程，希望能给遇到类似问题的朋友一点参考。

一、Mermaid 图表渲染问题与项目重建

最初的问题是博客中的 Mermaid 图表无法正常显示。在尝试了各种插件配置和主题调整后，我决定采取最彻底的方式：重建整个 Hexo 项目。

重建过程概览：

  1. 备份： 在动手前，备份了 source (文章)、_config.yml (站点配置)、_config.next.yml (Next 主题配置) 和 package.json (插件列表)。

  2. 删除旧项目： 在终端中进入 blog 目录的上一级，执行 rm -rf blog。

  3. 初始化新项目： 运行 hexo init blog，然后 cd blog。

  4. 安装插件和主题： 重新安装了 hexo-filter-mermaid-diagrams、hexo-deployer-git 等必要插件，并克隆安装了 Next 主题。

  5. 恢复配置和文章： 将备份的配置文件覆盖新生成的文件，把文章复制回 source 目录。

  6. 测试： 运行 hexo clean && hexo g && hexo s。

重建后，Mermaid 图表问题依旧存在，这让我意识到问题可能不只在 Hexo 本身。

二、浏览器端排查

既然 Hexo 配置看起来没问题，我将注意力转向了浏览器。

浏览器排查步骤：

  1. 无痕模式测试： 在 Chrome 或 Safari 中打开无痕窗口，访问 http://localhost:4000/。如果图表在此模式下正常显示，那问题多半是某个浏览器扩展程序（比如广告拦截插件）造成的。

  2. 开发者工具控制台： 如果无痕模式也无效，那就打开开发者工具（F12 或右键“检查”），切换到“控制台”（Console）选项卡，刷新页面。仔细查看是否有红色错误信息。这些信息是前端脚本加载或执行失败的直接线索。

三、版本兼容性问题

经过反复尝试，我开始思考是否是 Hexo 及其组件的版本兼容性问题。Hexo 的生态更新较快，老版本可能无法完美支持新插件或主题的特性。最终，通过彻底重建并确保所有组件都更新到最新、相互兼容的版本，之前遇到的许多奇怪问题才得以解决。这表明，统一组件版本对于 Hexo 博客的稳定性非常重要。

四、404 错误与 new_post_name 配置

在解决了渲染问题后，部署到线上又遇到了新的 404 错误。排查发现，一个不显眼的配置项是罪魁祸首：_config.yml 中的 new_post_name。

问题根源：

  • 如果 new_post_name 设置为 :category/title，Hexo 生成文章时会创建没有 .md 后缀的文件（例如 public/tech/my-article）。

  • Hexo 本地服务器可以正确处理这类文件，但大多数标准 Web 服务器（如 Nginx、GitHub Pages）在收到 http://yourdomain.com/tech/my-article 这样的请求时，会因为找不到明确的 .html 文件而返回 404。

解决方案：

将 _config.yml 中的 new_post_name 修改为：

YAML

1
new_post_name: :category/:title.md

修改后，务必执行 hexo clean && hexo g 清理并重新生成所有文件，然后重新部署。 这样 Hexo 就会生成带有 .html 扩展名的文件（例如 public/tech/my-article/index.html），Web 服务器就能正常识别并提供内容了。

总结

这次 Hexo 排查经历让我学到不少：

  1. 彻底重建是解决复杂环境问题的有效手段。

  2. 浏览器端排查是定位前端渲染问题的关键。

  3. 版本兼容性对 Hexo 博客至关重要，尽量保持各组件版本统一。

  4. new_post_name 这样的小细节也能导致部署后出现大面积 404。

希望这篇记录能帮到同样在使用 Hexo 的你。