HUGO 中文文档

  • 新闻
  • 文档
  • 主题
  • 社区
  • GitHub
gohugoio Star
  • 关于
    • 本节内容
    • 简介
    • 特性
    • 隐私
    • 安全
    • 许可证
  • 安装
    • 本节内容
    • macOS
    • Linux
    • Windows
    • BSD
  • 快速上手
    • 本节内容
    • 快速入门
    • 基本用法
    • 目录结构
    • 配置
    • 配置标记
    • 术语表
    • 配置构建
    • 外部学习资源
  • 快速参考
    • 本节内容
    • 表情符号
    • 函数
    • 方法
    • 页面集合
  • 内容管理
    • 本节内容
    • 组织
    • 页面包
    • 内容格式
    • Front matter (前置 matter)
    • 构建选项
    • 页面资源
    • 图片处理
    • 短代码
    • 相关内容
    • 章节
    • 内容类型
    • 原型
    • 分类法
    • 摘要
    • 链接和交叉引用
    • URL 管理
    • 菜单
    • 评论
    • 多语言
    • Markdown 属性
    • 语法高亮
    • 图表
    • 数学公式
    • 数据源
    • 内容适配器
  • 模板
    • 本节内容
    • 简介
    • 模板类型
    • 查找顺序
    • 基模板
    • 首页模板
    • 单个模板
    • 章节模板
    • 分类模板
    • 术语模板
    • 局部模板
    • 内容视图模板
    • 短代码模板
    • 站点地图模板
    • RSS 模板
    • 404 模板
    • robots.txt 模板
    • 菜单
    • 分页
    • 内嵌模板
    • 自定义输出格式
  • 函数
    • 本节内容
    • css
    • fmt
    • go 模板
    • hugo
    • js
    • lang
    • openapi3
    • os
    • urls
    • 全局
    • 加密
    • 反射
    • 变形
    • 变换
    • 哈希
    • 图像
    • 图表函数
    • 字符串
    • 安全函数
    • 局部模板函数
    • 数学
    • 数据
    • 时间
    • 模板
    • 比较
    • 类型转换
    • 编码
    • 调试
    • 资源
    • 路径
    • 集合
  • 方法
    • 本节内容
    • Duration
    • Menu
    • Page
    • Pager
    • Resource
    • Shortcode
    • Site
    • Taxonomy
    • Time
    • 菜单项
    • 页面
  • 渲染钩子
    • 本节内容
    • 简介
    • 块引用
    • 代码块
    • 标题
    • Images
    • 链接
    • Passthrough
    • 表格
  • Hugo 模块
    • 本节内容
    • 配置 Hugo 模块
    • 使用 Hugo 模块
    • 主题组件
  • Hugo 管道
    • 本节内容
    • 简介
    • 将 Sass 编译为 CSS
    • PostCSS
    • PostProcess
    • JavaScript 构建
    • 资源压缩
    • 连接资产
    • 指纹和 SRI 哈希
    • 从字符串创建资源
    • 从模板创建资源
  • 命令行界面
  • 故障排除
    • 本节内容
    • Audit
    • 日志记录
    • 检查
    • 弃用
    • 性能
    • FAQs
  • 开发者工具
    • 本节内容
    • 编辑器插件
    • 前端
    • Search
    • 迁移
    • 其他项目
  • 托管和部署
    • 本节内容
    • Hugo 部署
    • 使用 Rclone 部署
    • 使用 Rsync 部署
    • 在 21YunBox 上托管
    • 在 AWS Amplify 上托管
    • 在 Cloudflare Pages 上托管
    • 在 Firebase 上托管
    • 在 GitLab Pages 上托管
    • 在 Netlify 上托管
    • 在 Render 上托管
    • 托管在 Azure 静态 Web 应用上
    • 托管在 GitHub Pages 上
    • 托管在 KeyCDN 上
  • 贡献
    • 本节内容
    • 开发
    • 文档
    • 主题
  • 维护
CONTENT MANAGEMENT

URL 管理

通过 front matter 条目和站点配置中的设置来控制 URL 的结构和外观。

概述

默认情况下,当 Hugo 渲染页面时,生成的 URL 与 content 目录中的文件路径匹配。例如:

content/posts/post-1.md → https://example.org/posts/post-1/

您可以使用前置 matter 值和站点配置选项来更改 URL 的结构和外观。

前置 matter

slug

在 front matter 中设置 slug 以覆盖路径的最后一部分。 slug 值不影响章节页面。

content/posts/post-1.md
     
---
slug: my-first-post
title: 我的第一篇文章
---
+++
slug = 'my-first-post'
title = '我的第一篇文章'
+++
{
   "slug": "my-first-post",
   "title": "我的第一篇文章"
}

生成的 URL 将是:

https://example.org/posts/my-first-post/

url

在 front matter 中设置 url 以覆盖整个路径。将其与常规页面或章节页面一起使用。

Hugo 不会清理 url front matter 字段,允许您生成:

  • 包含操作系统保留字符的文件路径。例如,Windows 上的文件路径可能不包含任何这些 保留字符 。如果文件路径包含当前操作系统保留的字符,Hugo 将抛出错误。
  • 包含不允许的字符的 URL。例如,小于号( < )在 URL 中不允许。

如果您在 front matter 中同时设置 slug 和 url ,则 url 值优先。

包含冒号

New in v0.136.0

如果您需要在 url front matter 字段中包含冒号,请使用反斜杠字符对其进行转义。如果将字符串用单引号括起来,则使用一个反斜杠;如果将字符串用双引号括起来,则使用两个反斜杠。对于 YAML front matter,如果您省略引号,则使用单个反斜杠。

例如,使用此 front matter:

content/example.md
     
---
title: 示例
url: my\:example
---
+++
title = '示例'
url = 'my\:example'
+++
{
   "title": "示例",
   "url": "my\\:example"
}

生成的 URL 将是:

https://example.org/my:example/

如上所述,这在 Windows 上会失败,因为冒号( : )是保留字符。

文件扩展名

使用此 front matter:

content/posts/post-1.md
     
---
title: 我的第一篇文章
url: articles/my-first-article
---
+++
title = '我的第一篇文章'
url = 'articles/my-first-article'
+++
{
   "title": "我的第一篇文章",
   "url": "articles/my-first-article"
}

生成的 URL 将是:

https://example.org/articles/my-first-article/

如果您包含文件扩展名:

content/posts/post-1.md
     
---
title: 我的第一篇文章
url: articles/my-first-article.html
---
+++
title = '我的第一篇文章'
url = 'articles/my-first-article.html'
+++
{
   "title": "我的第一篇文章",
   "url": "articles/my-first-article.html"
}

生成的 URL 将是:

https://example.org/articles/my-first-article.html

前导斜杠

对于单语言站点,带有或不带有前导斜杠的 url 值相对于 baseURL 。对于多语言站点,带有前导斜杠的 url 值相对于 baseURL ,而没有前导斜杠的 url 值相对于 baseURL 加语言前缀。

站点类型 Front matter url 生成的 URL
单语言 /about https://example.org/about/
单语言 about https://example.org/about/
多语言 /about https://example.org/about/
多语言 about https://example.org/de/about/

前置 matter 中的永久链接标记

New in v0.131.0

您还可以在设置 url 值时使用 标记 。这通常用于 cascade 部分:

content/foo/bar/_index.md
     
---
cascade:
- url: /:sections[last]/:slug
title: Bar
---
+++
title = 'Bar'
[[cascade]]
  url = '/:sections[last]/:slug'
+++
{
   "cascade": [
      {
         "url": "/:sections[last]/:slug"
      }
   ],
   "title": "Bar"
}

站点配置

永久链接

在您的站点配置中,为每个顶级部分定义一个 URL 模式。每个 URL 模式都可以针对给定的语言和/或页面类型。

Front matter url 值会覆盖在站点配置的 permalinks 部分中定义的 URL 模式。

单语言示例

使用此内容结构:

content/
├── posts/
│   ├── bash-in-slow-motion.md
│   └── tls-in-a-nutshell.md
├── tutorials/
│   ├── git-for-beginners.md
│   └── javascript-bundling-with-hugo.md
└── _index.md

将教程渲染在“training”下,并将文章渲染在“articles”下,并使用基于日期的层次结构:

hugo.
     
permalinks:
  page:
    posts: /articles/:year/:month/:slug/
    tutorials: /training/:slug/
  section:
    posts: /articles/
    tutorials: /training/
[permalinks]
  [permalinks.page]
    posts = '/articles/:year/:month/:slug/'
    tutorials = '/training/:slug/'
  [permalinks.section]
    posts = '/articles/'
    tutorials = '/training/'
{
   "permalinks": {
      "page": {
         "posts": "/articles/:year/:month/:slug/",
         "tutorials": "/training/:slug/"
      },
      "section": {
         "posts": "/articles/",
         "tutorials": "/training/"
      }
   }
}

已发布站点的结构将是:

public/
├── articles/
│   ├── 2023/
│   │   ├── 04/
│   │   │   └── bash-in-slow-motion/
│   │   │       └── index.html
│   │   └── 06/
│   │       └── tls-in-a-nutshell/
│   │           └── index.html
│   └── index.html
├── training/
│   ├── git-for-beginners/
│   │   └── index.html
│   ├── javascript-bundling-with-hugo/
│   │   └── index.html
│   └── index.html
└── index.html

要为内容根目录中的常规页面创建基于日期的层次结构:

hugo.
     
permalinks:
  page:
    /: /:year/:month/:slug/
[permalinks]
  [permalinks.page]
    '/' = '/:year/:month/:slug/'
{
   "permalinks": {
      "page": {
         "/": "/:year/:month/:slug/"
      }
   }
}

对分类术语使用相同的方法。例如,要省略 URL 的分类术语段:

hugo.
     
permalinks:
  term:
    tags: /:slug/
[permalinks]
  [permalinks.term]
    tags = '/:slug/'
{
   "permalinks": {
      "term": {
         "tags": "/:slug/"
      }
   }
}

多语言示例

将 permalinks 配置用作本地化策略的一个组成部分。

使用此内容结构:

content/
├── en/
│   ├── books/
│   │   ├── les-miserables.md
│   │   └── the-hunchback-of-notre-dame.md
│   └── _index.md
└── es/
    ├── books/
    │   ├── les-miserables.md
    │   └── the-hunchback-of-notre-dame.md
    └── _index.md

以及此站点配置:

hugo.
     
defaultContentLanguage: en
defaultContentLanguageInSubdir: true
languages:
  en:
    contentDir: content/en
    languageCode: en-US
    languageDirection: ltr
    languageName: English
    permalinks:
      page:
        books: /books/:slug/
      section:
        books: /books/
    weight: 1
  es:
    contentDir: content/es
    languageCode: es-ES
    languageDirection: ltr
    languageName: Español
    permalinks:
      page:
        books: /libros/:slug/
      section:
        books: /libros/
    weight: 2
defaultContentLanguage = 'en'
defaultContentLanguageInSubdir = true
[languages]
  [languages.en]
    contentDir = 'content/en'
    languageCode = 'en-US'
    languageDirection = 'ltr'
    languageName = 'English'
    weight = 1
    [languages.en.permalinks]
      [languages.en.permalinks.page]
        books = '/books/:slug/'
      [languages.en.permalinks.section]
        books = '/books/'
  [languages.es]
    contentDir = 'content/es'
    languageCode = 'es-ES'
    languageDirection = 'ltr'
    languageName = 'Español'
    weight = 2
    [languages.es.permalinks]
      [languages.es.permalinks.page]
        books = '/libros/:slug/'
      [languages.es.permalinks.section]
        books = '/libros/'
{
   "defaultContentLanguage": "en",
   "defaultContentLanguageInSubdir": true,
   "languages": {
      "en": {
         "contentDir": "content/en",
         "languageCode": "en-US",
         "languageDirection": "ltr",
         "languageName": "English",
         "permalinks": {
            "page": {
               "books": "/books/:slug/"
            },
            "section": {
               "books": "/books/"
            }
         },
         "weight": 1
      },
      "es": {
         "contentDir": "content/es",
         "languageCode": "es-ES",
         "languageDirection": "ltr",
         "languageName": "Español",
         "permalinks": {
            "page": {
               "books": "/libros/:slug/"
            },
            "section": {
               "books": "/libros/"
            }
         },
         "weight": 2
      }
   }
}

已发布站点的结构将是:

public/
├── en/
│   ├── books/
│   │   ├── les-miserables/
│   │   │   └── index.html
│   │   ├── the-hunchback-of-notre-dame/
│   │   │   └── index.html
│   │   └── index.html
│   └── index.html
├── es/
│   ├── libros/
│   │   ├── les-miserables/
│   │   │   └── index.html
│   │   ├── the-hunchback-of-notre-dame/
│   │   │   └── index.html
│   │   └── index.html
│   └── index.html
└── index.html

标记

在定义 URL 模式时使用这些标记。您还可以在 front matter 中设置 url 值时使用这些标记。

:year
前置 matter date 字段中定义的 4 位数年份。
:month
前置 matter date 字段中定义的 2 位数月份。
:monthname
前置 matter date 字段中定义的月份名称。
:day
前置 matter date 字段中定义的 2 位数日期。
:weekday
前置 matter date 字段中定义的一位数星期几(星期日 = 0)。
:weekdayname
前置 matter date 字段中定义的星期几名称。
:yearday
前置 matter date 字段中定义的 1 到 3 位数的年份日数。
:section
内容的部分。
:sections
内容的部分层次结构。您可以使用 切片语法 选择部分部分: :sections[1:] 包含除第一个以外的所有部分, :sections[:last] 包含除最后一个以外的所有部分, :sections[last] 只包含最后一个部分, :sections[1:2] 包含部分 2 和 3。请注意,此切片访问不会引发任何越界错误,因此您不必精确。
:title
前置 matter 中定义的标题,否则为自动标题。Hugo 为非文件支持的章节、分类和术语页面自动生成标题。
:slug
前置 matter 中定义的 slug,否则为前置 matter 中定义的标题,否则为自动标题。Hugo 为非文件支持的章节、分类和术语页面自动生成标题。
:filename
内容的文件名(不含扩展名),适用于 page 页面类型。
:slugorfilename
前置 matter 中定义的 slug,否则为内容的文件名(不含扩展名),适用于 page 页面类型。

对于与时间相关的值,您还可以使用 Go 的 time 包 中定义的布局字符串组件。例如:

hugo.
     
permalinks:
  posts: /:06/:1/:2/:title/
[permalinks]
  posts = '/:06/:1/:2/:title/'
{
   "permalinks": {
      "posts": "/:06/:1/:2/:title/"
   }
}

外观

URL 的外观要么难看,要么漂亮。

类型 路径 URL
难看 content/about.md https://example.org/about.html
漂亮 content/about.md https://example.org/about/

默认情况下,Hugo 生成漂亮的 URL。要生成难看的 URL,请更改您的站点配置:

hugo.
     
uglyURLs: true
uglyURLs = true
{
   "uglyURLs": true
}

您也可以按部分启用 uglyURLs。例如,对于包含书籍和电影部分的站点:

hugo.
     
uglyURLs:
  books: true
  films: false
[uglyURLs]
  books = true
  films = false
{
   "uglyURLs": {
      "books": true,
      "films": false
   }
}

后处理

Hugo 提供了两个相互排斥的配置选项,用于在渲染页面 之后 更改 URL。

规范 URL

这是一个旧的配置选项,已被模板函数和 Markdown 渲染钩子取代,并且可能在 未来的版本中删除 。

如果启用,Hugo 将在渲染页面 之后 执行搜索和替换。它搜索与 action 、 href 、 src 、 srcset 和 url 属性关联的站点相关 URL(那些带有前导斜杠的 URL)。然后它将 baseURL 添加到前面以创建绝对 URL。

<a href="/about"> → <a href="https://example.org/about/">
<img src="/a.gif"> → <img src="https://example.org/a.gif">

这是一种不完善的蛮力方法,它可能会影响内容以及 HTML 属性。如上所述,这是一个旧的配置选项,可能会在未来的版本中删除。

要启用:

hugo.
     
canonifyURLs: true
canonifyURLs = true
{
   "canonifyURLs": true
}

相对 URL

除非您正在创建无服务器站点(通过文件系统导航),否则不要启用此选项。

如果启用,Hugo 将在渲染页面 之后 执行搜索和替换。它搜索与 action 、 href 、 src 、 srcset 和 url 属性关联的站点相关 URL(那些带有前导斜杠的 URL)。然后它将 URL 转换为相对于当前页面的 URL。

例如,在渲染 content/posts/post-1 时:

<a href="/about"> → <a href="../../about">
<img src="/a.gif"> → <img src="../../a.gif">

这是一种不完善的蛮力方法,它可能会影响内容以及 HTML 属性。如上所述,除非您正在创建无服务器站点,否则不要启用此选项。

要启用:

hugo.
     
relativeURLs: true
relativeURLs = true
{
   "relativeURLs": true
}

别名

使用别名创建从旧 URL 到新 URL 的重定向:

  • 带有前导斜杠的别名相对于 baseURL
  • 没有前导斜杠的别名相对于当前目录

示例

更改现有页面的文件名,并从之前的 URL 创建到新 URL 的别名:

content/posts/new-file-name.md.
     
aliases:
- /posts/previous-file-name
aliases = ['/posts/previous-file-name']
{
   "aliases": [
      "/posts/previous-file-name"
   ]
}

这些目录相关的别名都等同于上面的站点相关的别名:

  • previous-file-name
  • ./previous-file-name
  • ../posts/previous-file-name

您可以为当前页面创建多个别名:

content/posts/new-file-name.md.
     
aliases:
- previous-file-name
- original-file-name
aliases = ['previous-file-name', 'original-file-name']
{
   "aliases": [
      "previous-file-name",
      "original-file-name"
   ]
}

在多语言站点中,使用目录相关的别名,或在站点相关的别名中包含语言前缀:

content/posts/new-file-name.de.md.
     
aliases:
- /de/posts/previous-file-name
aliases = ['/de/posts/previous-file-name']
{
   "aliases": [
      "/de/posts/previous-file-name"
   ]
}

别名的工作原理

使用上面的第一个示例,Hugo 生成以下站点结构:

public/
├── posts/
│   ├── new-file-name/
│   │   └── index.html
│   ├── previous-file-name/
│   │   └── index.html
│   └── index.html
└── index.html

从之前的 URL 到新 URL 的别名是客户端重定向:

posts/previous-file-name/index.html
<!DOCTYPE html>
<html lang="en-us">
  <head>
    <title>https://example.org/posts/new-file-name/</title>
    <link rel="canonical" href="https://example.org/posts/new-file-name/">
    <meta name="robots" content="noindex">
    <meta charset="utf-8">
    <meta http-equiv="refresh" content="0; url=https://example.org/posts/new-file-name/">
  </head>
</html>

head 部分中的元素共同作用:

  • 告诉搜索引擎新的 URL 是规范的
  • 告诉搜索引擎不要索引之前的 URL
  • 告诉浏览器重定向到新的 URL

Hugo 在渲染页面之前渲染别名文件。使用先前文件名的新的页面将按预期覆盖别名。

自定义

要覆盖 Hugo 内置的 alias 模板,请将 源代码 复制到布局目录中具有相同名称的文件中。模板接收以下上下文:

永久链接
被创建别名的页面的链接。
页面
被创建别名的页面的页面数据。

See also

  • Front matter (前置 matter)
  • 组织
  • 文档
  • 数学公式
  • Markdown 属性

On this page

  • 概述
  • 前置 matter
  • 站点配置
  • 别名
Last updated: January 10, 2025: 添加 gtm 谷歌代码管理 (6220bf5)
Improve this page
By the Hugo Authors
Hugo Logo
  • File an Issue
  • Get Help
  • @GoHugoIO
  • @spf13
  • @bepsays
 

Hugo Sponsors

Your Company?
 

The Hugo logos are copyright © Steve Francia 2013–2025.

The Hugo Gopher is based on an original work by Renée French.

  • 新闻
  • 文档
  • 主题
  • 社区
  • GitHub
  • 关于
  • 安装
  • 快速上手
  • 快速参考
  • 内容管理
  • 模板
  • 函数
  • 方法
  • 渲染钩子
  • Hugo 模块
  • Hugo 管道
  • 命令行界面
  • 故障排除
  • 开发者工具
  • 托管和部署
  • 贡献
  • 维护