Hexo Aurora 主题中文导航栏空白问题的排查与修复

在使用 Hexo 搭建博客并配置 Aurora 主题时，我们遇到了一个非常典型且隐蔽的 Bug：在增加自定义导航目录时，如果使用的是中文环境，导航栏上会显示空白的按钮，而英文环境下却能正常显示文字。

这篇文档记录了整个问题的排查思路与最终的修复过程，希望对遇到相同问题的开发者有所帮助。

1. 问题现象

在 _config.aurora.yml 中新增了自定义导航目录，比如 technology (技术)、growth (成长) 等，并且按照官方文档的要求配置了 name、path 和 i18n 属性：

technology:
  name: 'technology'
  path: '/page/technology'
  i18n:
    cn: '技术'
    zh-CN: '技术'
    en: 'Technology'

但在本地预览时，发现只有英文环境能正常显示 “Technology”，当语言切换到中文时，对应的导航按钮上只有背景颜色，文字完全不显示（空白）。

2. 初步排查与踩坑

2.1 怀疑是数据未加载

最初怀疑是因为这些新增页面没有实质的 Markdown 内容导致。但在补充了对应目录下的 index.md 文件并添加了 front-matter 后，问题依旧。

2.2 尝试外部脚本注入 (失败)

接着怀疑是主题的渲染逻辑问题。由于直接修改前端打包后的 Vue 源码比较危险，我们尝试了在 _config.aurora.yml 的 injects.scripts 中注入一个基于 MutationObserver 的 JS 补丁，试图在页面加载后强行修改 DOM 节点填充中文字符。

结果：补丁并未生效。
原因在于 Aurora 主题是一个基于 Vue 3 构建的单页应用 (SPA)。Vue 的响应式系统 (Virtual DOM) 在每次路由切换或状态更新时都会重新渲染真实 DOM，从而无情地覆盖掉了我们外部注入脚本对 DOM 的修改。

3. 深入源码：寻找病灶

既然外部补丁无效，只能直接深入分析主题编译后的前端包（hexo-theme-aurora/source/static/js/）。
通过排查，发现了两个导致该问题的核心因素：

3.1 Vue-i18n 的严格匹配与降级机制

前端代码在渲染导航栏时，是根据当前的 locale 变量去 route.i18n 字典里取值的（如 c.i18n[e.locale]）。
而 Aurora 主题内置的中文语言包的标准标识是 **zh-CN**，并非 cn。

如果在站点的 _config.yml 或 _config.aurora.yml 中，将 language 错误地配置成了 cn：

language: cn

前端的 Vue-i18n 多语言插件在初始化时，会找不到名为 cn 的语言包。一旦匹配失败，它就会触发降级机制，自动回退到它的后备语言（fallbackLocale），也就是英文 en。

这就解释了为什么中文环境下会显示空白或英文：因为当前的 locale 实际上被强制降级成了 en，而如果我们没有在配置里写全对应标识，就会取不到值。

3.2 hexo-plugin-aurora 的 API 生成阻断 (Node 24+ 环境)

在排查配置未生效的过程中，我们还发现了一个更为隐蔽的环境兼容性问题。

Aurora 主题的数据（如菜单配置）是依靠 hexo-plugin-aurora 这个插件生成 JSON 文件（如 api/site.json），然后供前端拉取渲染的。
但是，在较新的 Node.js 版本（如 Node v24+）下，该插件内部依赖的一个名为 deasync 的模块（用于代码高亮组件同步化）会因为找不到 C++ 的 bindings 编译产物而抛出异常。

最致命的是，原本代码中没有对这个异常进行捕获：

// hexo-plugin-aurora/index.js 源码中
require('./lib/highlighter')(hexo); // 这里在 Node 24 会抛错并阻断后续执行
require('./lib/generators')(hexo);  // 导致 API JSON 生成逻辑根本没跑

由于高亮模块的报错阻断了整个流程，导致 hexo generate 虽然看似跑完了，但实际上并没有生成最新的 api/site.json。因此，前端不论怎么刷新，拿到的永远是旧的数据，菜单配置自然无法生效。

4. 最终解决方案

明确了病因后，解决起来就非常简单了。

步骤一：修正语言标识为 zh-CN
打开站点的根目录 _config.yml 和 Aurora 的 _config.aurora.yml，确保语言配置是规范的：

# 正确配置
language: zh-CN

步骤二：修复插件的报错阻断
进入 node_modules/hexo-plugin-aurora/index.js，为可能出错的高亮模块添加 try-catch，保证即使高亮模块失效，也不会影响核心数据的生成：

// 修改前
require('./lib/highlighter')(hexo);

// 修改后
try {
  require('./lib/highlighter')(hexo);
} catch (e) {
  console.warn('Highlighter failed to load', e.message);
}

步骤三：清理并重新生成
清理缓存并重新生成站点：

hexo clean
hexo g
hexo s

5. 总结

1. Vue 的响应式特性决定了在处理类似前端渲染主题的问题时，外部强行修改 DOM 往往是徒劳的，应该优先排查数据源和渲染逻辑。
2. 严格遵守配置规范。语言标识等字段不能随意简写（如把 zh-CN 写成 cn），否则极易触发第三方库（如 Vue-i18n）的隐式降级。
3. 警惕 Node 版本兼容性。老旧的 Hexo 插件（特别是包含 C++ 原生扩展如 deasync 的包）在高版本 Node 环境下极易报错，必要时需要手动打补丁或降级 Node 版本。