hexo 学习 0022:hexo 数据文件

在 Hexo 博客开发中，你经常会遇到一些需要在多个页面或模板中重复使用的数据，比如导航菜单、友情链接列表、团队成员信息或是特定的配置参数。如果把这些数据硬编码在每一个模板文件里，一旦需要修改，你就得逐个文件去更新，既繁琐又容易出错。

Hexo 3 引入的“数据文件（Data Files）”功能，就是为了解决这个问题。你可以把它想象成博客的“公共数据库”或“共享变量库”。你只需要把数据集中存放在一个地方，然后在任何模板中随时调用，实现“一次定义，多处使用”。

核心概念与目录结构

数据文件的核心在于 source/_data 目录。这是 Hexo 专门预留的文件夹，用于存放全局共享的数据文件。

• 存放位置：source/_data/
• 支持格式：YAML (.yml) 或 JSON (.json)。推荐使用 YAML，因为语法更简洁，可读性更强。
• 访问方式：在模板中通过 site.data.<文件名> 对象来访问。

比喻说明：
如果把 Hexo 的模板比作“厨房”，文章是“食材”，那么 source/_data 就是一个“中央调料柜”。你不需要在每个灶台（模板）上都放一瓶盐（数据），只需要在中央柜子里放好，哪个灶台需要，伸手取用即可。

配置示例：创建数据文件

假设你需要在网站页脚或侧边栏显示一个统一的导航菜单。

步骤 1：创建文件
在 source/_data 目录下新建一个名为 menu.yml 的文件。

步骤 2：编写数据
使用 YAML 格式写入键值对。键（Key）将作为显示文本，值（Value）将作为链接地址。

# source/_data/menu.yml
Home: /
Gallery: /gallery/
Archives: /archives/
About: /about/
Contact: /contact/

如果你更喜欢 JSON 格式，也可以创建 menu.json：

{
  "Home": "/",
  "Gallery": "/gallery/",
  "Archives": "/archives/"
}

模板调用方法

数据加载是自动的。一旦你在 _data 目录下创建了文件，Hexo 会在生成网站时自动读取它们，并将其挂载到 site.data 对象下。对象的名字就是你的文件名（不含扩展名）。

调用语法：
site.data.<文件名>

代码示例：
在你的主题模板文件（例如 layout/_partial/header.ejs 或 .swig / .njk）中，使用循环遍历数据并生成 HTML。

以下以 EJS 模板引擎为例：

<nav class="main-menu">
  <% for (var link in site.data.menu) { %>
    <a href="<%= site.data.menu[link] %>"> <%= link %> </a>
  <% } %>
</nav>

代码解析：

1. site.data.menu：对应 source/_data/menu.yml 文件。如果你的文件叫 links.yml，这里就写成 site.data.links。
2. for (var link in ...)：遍历 YAML 中的每一个键（即 “Home”, “Gallery” 等）。
3. site.data.menu[link]：获取对应的值（即 “/“, “/gallery/“ 等）。

渲染结果：
上述代码在生成静态网页时，会被渲染为：

<nav class="main-menu">
  <a href="/"> Home </a>
  <a href="/gallery/"> Gallery </a>
  <a href="/archives/"> Archives </a>
  <a href="/about/"> About </a>
  <a href="/contact/"> Contact </a>
</nav>

概念辨析：数据文件 vs Front-matter

新手容易混淆 Front-matter 和 数据文件，虽然它们都使用 YAML 格式，但作用域完全不同。

特性	Front-matter	数据文件 (Data Files)
位置	位于每篇文章 Markdown 文件的顶部	位于 source/_data/ 目录下的独立文件
作用域	局部。仅对当前这篇文章有效	全局。对整个网站的所有模板有效
访问方式	在模板中通过 page.字段名 访问	在模板中通过 site.data.文件名.字段名 访问
典型用途	设置单篇文章的标题、日期、标签、摘要	设置全站导航、友情链接、作者信息、通用配置
比喻	身份证（个人的专属信息）	电话簿（大家都可以查阅的公共信息）

进阶应用场景

除了导航菜单，数据文件还非常适合以下场景：

1. 友情链接列表
   创建 friends.yml，存储朋友的博客名称和 URL，在侧边栏统一调用，方便随时增删。
2. 团队成员介绍
   创建 team.yml，存储成员姓名、职位、头像路径，在“关于我们”页面循环展示。
3. 多语言配置
   对于简单的站点文案，可以用 lang.yml 存储不同语言的字符串，配合逻辑判断实现简易的多语言切换。

注意事项

1. 文件名规范：文件名即为你在模板中调用的变量名。建议使用小写字母和下划线（如 site_links.yml），避免使用特殊字符或空格，以免在模板中引用时出错。
2. 格式严格：YAML 对缩进非常敏感。请确保使用空格进行缩进（通常是 2 个空格），不要使用 Tab 键，否则会导致 Hexo 解析失败。
3. 生效时机：修改 _data 下的文件后，通常需要重新运行 hexo generate 或 hexo server 才能看到变化。Hexo 不会像监听文章那样实时热重载数据文件（取决于具体版本和配置，建议手动重启服务以确保稳妥）。
4. 数据类型：数据文件不仅支持简单的键值对，也支持列表和嵌套对象。
   • 列表示例 (skills.yml)：

     - JavaScript
     - Python
     - Go

     调用：<% site.data.skills.forEach(function(skill) { %><li><%= skill %></li><% }); %>

通过合理使用数据文件，你可以将内容与表现彻底分离，让 Hexo 博客的结构更加清晰，维护起来也更加轻松。

Data Files 使用

数据文件（Data Files）是 Hexo 3 版本之后内置的核心功能。只要你的 Hexo 版本在 3.0 以上（目前主流版本远高于此），就可以直接使用，无需执行 npm install 安装任何插件。

要在博客中实际使用它，只需遵循以下三个步骤：

第一步：创建数据文件夹

检查你的博客根目录下的 source 文件夹。

• 如果里面已经有 _data 文件夹，直接使用。
• 如果没有，请手动新建一个名为 _data 的文件夹。
  • 路径应为：你的博客根目录/source/_data

第二步：创建数据文件

在 source/_data 文件夹内，创建一个 YAML 或 JSON 文件。

• 文件名：随意取，但要用英文小写，方便后续调用（例如 friends.yml）。
• 内容：按照 YAML 格式填写数据。

示例：创建一个友情链接列表
新建文件 source/_data/friends.yml，内容如下：

Hexo官方: https://hexo.io/
GitHub: https://github.com/
Google: https://www.google.com/

第三步：在模板中调用

这是最关键的一步。你需要编辑你的主题模板文件（通常是 .ejs、.swig 或 .njk 后缀），将数据渲染到页面上。

注意：你不能直接在文章的 Markdown 内容（.md 文件）中使用 <% %> 这种代码，因为 Markdown 只负责文章内容。数据文件主要用于布局模板（如侧边栏、页脚、导航栏）。

操作位置示例：
假设你想在侧边栏显示友情链接，你需要找到主题文件夹下的侧边栏模板文件。

• 路径通常在：themes/你的主题名/layout/_partial/sidebar.ejs (具体路径视主题而定)

调用代码示例 (以 EJS 为例)：
在模板文件中插入以下代码：

<div class="friend-links">
  <h3>友情链接</h3>
  <ul>
    <!-- site.data.文件名 对应 source/_data/文件名.yml -->
    <% for (var name in site.data.friends) { %>
      <li>
        <a href="<%= site.data.friends[name] %>" target="_blank">
          <%= name %>
        </a>
      </li>
    <% } %>
  </ul>
</div>

代码逻辑解析：

1. site.data.friends：自动读取 source/_data/friends.yml 的内容。
2. for (var name in ...)：遍历 YAML 中的每一行。name 变量会依次变成 “Hexo官方”, “GitHub” 等键名。
3. site.data.friends[name]：获取对应的链接地址。

第四步：生成预览

保存所有文件后，在终端运行：

hexo clean
hexo generate
hexo server

打开浏览器访问本地博客，你刚才定义的友情链接就会出现在侧边栏了。

常见疑问解答

Q: 我能在文章正文（.md 文件）里直接用吗？
A: 不能直接写代码。Markdown 文章里无法运行 <% %> 模板代码。

• 解决方案 1：像上面演示的那样，把数据放在侧边栏或页脚等公共区域。
• 解决方案 2：如果你非要在某篇文章里显示特定数据，通常需要通过自定义短代码（Shortcode）或者在主题模板中判断当前页面路径来显示，这比直接在侧边栏显示要复杂一些。对于大多数用户，将数据文件用于全站通用的模块（导航、友链、作者信息）是最佳实践。

Q: 修改了 yml 文件为什么没变化？
A: Hexo 有时不会自动监听 _data 目录的变化。如果修改后没生效，请尝试停止服务器，运行 hexo clean 清除缓存，然后重新 hexo generate 和 hexo server。

总结：

1. 无需安装包。
2. 在 source/_data 建文件。
3. 在 themes/.../layout 下的模板文件中写代码调用 site.data.文件名。
4. 重新生成即可。