hexo 学习►自定义配置

hexo 学习 0025:hexo permalinks

永久链接（Permalinks）决定了你博客中每篇文章的最终网址结构。一个清晰、规范的网址不仅有利于搜索引擎优化（SEO），还能让读者通过网址直接判断文章的大致内容和发布时间。在 Hexo 中，你可以像搭积木一样，通过组合不同的变量来定制这个网址。

核心配置位置

永久链接的配置主要有两个层级：

  1. 全局配置：在博客根目录的 _config.yml 文件中设置 permalink 参数，这将应用于所有文章。
  2. 局部配置：在单篇文章的 Front-matter（文件顶部的 YAML 区域）中指定 permalink，这将覆盖全局设置，仅对该文章生效。

比喻说明：
全局配置就像是公司的“统一着装规定”，所有人都默认遵守；而 Front-matter 中的配置则像是“特批令”，允许特定员工在特定场合穿便装。

可用变量详解

Hexo 提供了一系列变量，代表文章的不同属性。除了 :path 和 :permalink 这两个特殊属性外，Front-matter 中的所有自定义属性也可以作为变量使用。

变量 描述 示例值 (基于 2013-07-14)
:year 文章发表年份（4 位数） 2013
:month 文章发表月份（2 位数，含前导零） 07
:i_month 文章发表月份（不含前导零） 7
:day 文章发表日期（2 位数，含前导零） 14
:i_day 文章发表日期（不含前导零） 14
:hour 文章发表小时（2 位数） 17
:minute 文章发表分钟（2 位数） 01
:second 文章发表秒钟（2 位数） 34
:timestamp 文章发布日期的 Unix 时间戳 1373824894
:title 文件名称（相对于 source/_posts/，不含子目录） hello-world
:name 文件名称（同上，通常与 title 行为一致） hello-world
:post_title 文章标题（Front-matter 中的 title 字段） Hello World
:id 文章 ID（注意：清除缓存 hexo clean 后可能会改变，不具备持久性） 12345
:category 分类路径。若无分类，则使用配置中的 default_category foo/bar
:hash 文件名与日期的 SHA1 哈希值（12 位 16 进制数），用于防止重复 a2c8ac003b43

配置示例与效果演示

假设你有一篇文章位于 source/_posts/hello-world.md，其 Front-matter 如下：

1
2
3
4
5
title: Hello World
date: 2013-07-14 17:01:34
categories:
  - foo
  - bar

你在 _config.yml 中设置不同的 permalink 格式，生成的网址如下：

示例 1：按日期归档（经典博客风格）
配置：

1
permalink: :year/:month/:day/:title/

结果网址：
.../2013/07/14/hello-world/

示例 2：HTML 静态文件风格
配置：

1
permalink: :year-:month-:day-:title.html

结果网址：
.../2013-07-14-hello-world.html

示例 3：按分类归档（知识库风格）
配置：

1
permalink: :category/:title/

结果网址：
.../foo/bar/hello-world/
注意：这里会自动根据 front-matter 中的 categories 生成多级目录。

示例 4：防重复短链接
配置：

1
permalink: :title-:hash/

结果网址：
.../hello-world-a2c8ac003b43/
注意：:hash 由文件名和日期计算得出，即使两篇文章标题相同，只要日期或文件名不同，哈希值也会不同，从而避免网址冲突。

特殊情况：子目录文件
如果文章位于子目录，例如 source/_posts/lorem/hello-world.md：

  • 使用 :title 变量时，会包含子目录名：.../2013/07/14/lorem/hello-world/
  • 使用 :name 变量时，通常只取文件名部分：.../2013/07/14/hello-world/
    (注：具体行为可能受 Hexo 版本细微差异影响，建议实际测试确认 :name 和 :title 在子目录下的表现，素材中显示 :title 包含了 lorem)

默认值设置

如果你希望在永久链接中使用自定义变量（例如多语言站点中的 :lang），你需要在 permalink_defaults 参数下定义这些变量的默认值。

配置示例：

1
2
3
permalink: :lang/:title/
permalink_defaults:
  lang: en

作用说明：
当某篇文章的 Front-matter 中没有指定 lang 属性时，Hexo 会自动使用 en 作为默认值。如果文章中写了 lang: zh-cn，则使用该值。这保证了链接结构的稳定性，不会因为缺少字段而报错。

多语种支持实战

构建多语言网站时，永久链接的配合至关重要。你需要同时修改新建文章的命名规则和永久链接规则。

步骤 1：修改配置
在 _config.yml 中设置：

1
2
new_post_name: :lang/:title.md
permalink: :lang/:title/
  • new_post_name：决定使用 hexo new 命令创建文章时，文件保存的路径和名称。
  • permalink：决定最终生成的网址。

步骤 2：创建文章
使用 --lang 参数创建新文章：

1
hexo new "Hello World" --lang tw

执行结果：

  • 文件路径：文章将被保存到 source/_posts/tw/Hello-World.md。
  • 生成网址：访问地址将是 http://localhost:4000/tw/hello-world/。

这种配置方式将语言代码直接融入网址结构，既有利于用户识别语言，也有利于搜索引擎进行地域和语言定位。

概念辨析：:title vs :name vs :post_title

这三个变量都与“名字”有关，但来源和含义不同：

  • :title：源自文件名。它是文件在磁盘上的名字（去掉扩展名）。如果文件在子文件夹中，它通常包含文件夹路径。它是 URL 友好化的（空格变连字符）。
  • :name：通常也指文件名，但在某些上下文中可能不包含子目录路径。在大多数基础用法中，它与 :title 表现相似，但在处理嵌套目录时需留意差异。
  • :post_title：源自Front-matter 中的 title 字段。这是你给文章起的正式标题，可以包含空格、中文等特殊字符。直接用于 URL 时通常需要进行编码或替换，否则可能导致链接过长或乱码。

建议：在构建永久链接时，优先使用 :title 或 :hash 以保证 URL 的简洁和规范；:post_title 更适合用于页面内的 <h1> 标题显示，而非网址本身。

注意事项

  1. ID 的不持久性：尽量避免在生产环境中使用 :id 变量。当你运行 hexo clean 清除缓存时，文章 ID 可能会重新生成，导致旧链接失效，产生 404 错误。
  2. URL 规范化：Hexo 会自动处理变量中的特殊字符（如将空格转换为 -），但为了最佳兼容性，建议文件名和标题尽量使用英文小写和连字符。
  3. 修改后的生效：修改 _config.yml 中的 permalink 设置后，必须运行 hexo clean 然后 hexo generate 重新生成所有文件，新的链接结构才会生效。否则，旧的链接结构可能仍残留在 public 目录中。