配置

永久链接配置

用 pattern 与目标匹配器自定义页面 URL 的生成规则。

这一页解决什么问题

permalinks 用模式字符串决定页面的 URL 长什么样,例如 /:year/:month/:slug/。不加配置时,URL 直接照内容目录结构生成;这一页处理的是「目录结构 ≠ 你想要的 URL」的情况。

改这里等于改站点的 URL 空间:旧链接会失效、站点地图会变、外部反链会 404。规模较大的站点要配合别名(alias)与平台重定向一起改。

什么时候需要这些设置

设置 什么时候需要 改错了会看到什么现象
映射形式 按顶级区段统一改 URL(例如 articles 全部走 /blog/…) 区段名写错 → 模式不匹配任何页面,URL 保持原样,且不报错
数组形式 + target 只对部分页面(按路径、类型、环境、多语言)套用模式 上游明确「采用第一个匹配成功的模式」;把兜底模式写在数组前面,后面的精确规则就永远轮不到
target.sites.matrix 多语言 / 多版本站点各用不同的 URL 语言名写错 → 该语言落到兜底模式,链接结构与其他语言不一致
前置元数据 url 单个页面需要固定地址 url 会覆盖任何与之匹配的永久链接模式(上游原话);排查「这页为什么不守规则」时先看它

概述

permalinks 配置用于为页面定义自定义 URL 模式。Hugo 支持两种书写形式:

形式 结构 适用场景
映射形式(map) 按页面类型(page kind)分组的键值对 按顶级区段统一指定模式
数组形式(array) 由若干条 pattern 条目组成的数组 需要用页面匹配器精确定位页面子集

映射形式

以页面类型(page kind)为键,为每个顶级区段定义 URL 模式。例如为 articles 区段配置模式:

toml
[permalinks.page]
articles = '/blog/:year/:month/:slug/'

[permalinks.section]
articles = '/blog/'

可用的页面类型键如下:

键名 作用范围
page 普通内容页。
section 区段页。
term 分类法术语页。
taxonomy 分类法列表页。

每个键之下再以区段名为键,值是模式字符串。

按语言配置时,把 permalinks 区段嵌在语言键之下:

toml
[languages]
  [languages.de]
    label = 'Deutsch'
    locale = 'de-DE'
    weight = 1
    [languages.de.permalinks]
      [languages.de.permalinks.page]
        articles = '/artikel/:year/:month/:slug/'
      [languages.de.permalinks.section]
        articles = '/artikel/'
  [languages.en]
    label = 'English'
    locale = 'en-US'
    weight = 2
    [languages.en.permalinks]
      [languages.en.permalinks.page]
        articles = '/blog/:year/:month/:slug/'
      [languages.en.permalinks.section]
        articles = '/blog/'

数组形式

定义一个永久链接条目数组,把不同的 URL 模式应用到不同的页面子集。每个条目必须有 pattern 键,Hugo 采用第一个匹配成功的模式。

可选的 target 键接受一个页面匹配器;省略 target 时,该模式应用于所有页面。

键名 类型 是否必填 含义
pattern string 是 URL 模式,可包含下方 token 表中的标记。
target map 否 页面匹配器,用于限定该条目作用的页面范围。

页面匹配器支持以下关键字:

关键字 类型 含义
environment string 匹配构建环境的 glob 模式,例如 {staging,production}。
kind string 匹配页面类型的 glob 模式,例如 {taxonomy,term}。
path string 匹配页面逻辑路径的 glob 模式,例如 {/books,/books/**}。
sites map 站点矩阵,匹配语言、版本、角色等任意内容维度组合。

例如,分别为 articles 区段页与其叶子页面应用语言相关的 URL 模式:

toml
[[permalinks]]
  pattern = '/artikel/'
  [permalinks.target]
    path = '{/articles}'
    [permalinks.target.sites]
      [permalinks.target.sites.matrix]
        languages = ['de']

[[permalinks]]
  pattern = '/artikel/:year/:month/:slug/'
  [permalinks.target]
    path = '{/articles/**}'
    [permalinks.target.sites]
      [permalinks.target.sites.matrix]
        languages = ['de']

[[permalinks]]
  pattern = '/blog/'
  [permalinks.target]
    path = '{/articles}'
    [permalinks.target.sites]
      [permalinks.target.sites.matrix]
        languages = ['en']

[[permalinks]]
  pattern = '/blog/:year/:month/:slug/'
  [permalinks.target]
    path = '{/articles/**}'
    [permalinks.target.sites]
      [permalinks.target.sites.matrix]
        languages = ['en']

若要为非此前所有条目都未匹配到的页面提供兜底,把不带 target 键的模式放在数组末尾:

toml
[[permalinks]]
pattern = '/:section/:slug/'

可用 token

在模式字符串中可使用下列 token。

token 含义
:year 前置元数据 date 字段中的 4 位年份。
:month 前置元数据 date 字段中的 2 位月份。
:monthname 前置元数据 date 字段中的月份名称。
:day 前置元数据 date 字段中的 2 位日期。
:weekday 前置元数据 date 字段中的 1 位星期序号(星期日为 0)。
:weekdayname 前置元数据 date 字段中的星期名称。
:yearday 前置元数据 date 字段中的年内第几天,1 至 3 位。
:section 内容所属区段。
:sectionslug 内容所属区段的 slug 化名称(自 v0.149.0 起可用)。
:sections 内容的区段层级,支持切片语法,如 :sections[1:]、:sections[:last]、:sections[last]、:sections[1:2]。
:sectionslugs 区段层级的 slug 化名称,同样支持切片语法(自 v0.149.0 起可用)。
:title 前置元数据 title,否则为自动标题。
:slug 前置元数据 slug,否则为 title,否则为自动标题。
:filename 已废弃(v0.144.0),请改用 :contentbasename。
:slugorfilename 已废弃(v0.144.0),请改用 :slugorcontentbasename。
:contentbasename 内容基础名(自 v0.144.0 起可用)。
:slugorcontentbasename 前置元数据 slug,否则为内容基础名(自 v0.144.0 起可用)。

其中 slug 化名称取自前置元数据 slug,否则取自 title,否则取自动标题。切片访问不会抛出越界错误,因此无需精确计算下标。

时间相关的值也可以使用 Go time 包 中定义的时间布局组件,例如:

toml
permalinks:
  posts: /:06/:1/:2/:title/

常见坑

症状 真因 怎么修
改了 permalinks,页面 URL 没变 区段名或页面类型键写错,模式没匹配上;Hugo 不报错 先用最小范围验证(只配一个区段),确认生效后再扩展
只有部分页面用了新模式 数组形式的 target 没覆盖到它们,或被更靠前的条目拦下 检查条目顺序:Hugo 取第一个匹配成功的模式,兜底条目必须放在最后
某页怎么都不按规则走 该页前置元数据里写了 url,它的优先级最高 删掉该页的 url,或就用 url 明确写死
旧链接全部 404 模式改动改变了既有地址 为受影响的页面加 aliases(见 URL 管理),并在部署平台上配置重定向
提示 token 已废弃,或结果为空 :filename、:slugorfilename 自 v0.144.0 起已废弃 改用 :contentbasename 与 :slugorcontentbasename

更多排查入口见故障排查。