HUGO

  • 新闻
  • 文档
  • 主题
  • 社区
  • GitHub
gohugoio 加星
  • 关于
    • 本节内容
    • 简介
    • 特性
    • 隐私
    • 安全
    • 许可
  • 安装
    • 本节内容
    • macOS
    • Linux
    • Windows
    • BSD
  • 入门
    • 本节内容
    • 快速开始
    • 基本用法
    • 目录结构
    • 配置
    • 配置标记
    • 配置构建
    • 术语表
    • 外部学习资源
  • 快速参考
    • 本节内容
    • 表情符号
    • 函数
    • 方法
    • 页面集合
  • 内容管理
    • 本节内容
    • 组织
    • 页面包
    • 内容格式
    • 前言
    • 构建选项
    • 页面资源
    • 图像处理
    • 短代码
    • 相关内容
    • 章节
    • 内容类型
    • 原型
    • 分类法
    • 摘要
    • 链接和交叉引用
    • URL 管理
    • 菜单
    • 评论
    • 多语言
    • Markdown 属性
    • 语法高亮
    • 图表
    • 数学
    • 数据源
    • 内容适配器
  • 模板
    • 本节内容
    • 简介
    • 模板类型
    • 查找顺序
    • 基础模板
    • 主页模板
    • 单页模板
    • 章节模板
    • 分类法模板
    • 术语模板
    • 部分模板
    • 内容视图模板
    • 短代码模板
    • 站点地图模板
    • RSS 模板
    • 404 模板
    • robots.txt 模板
    • 菜单
    • 分页
    • 嵌入式模板
    • 自定义输出格式
  • 函数
    • 本节内容
    • cast
    • collections
    • compare
    • crypto
    • css
    • data
    • debug
    • diagrams
    • encoding
    • fmt
    • global
    • go template
    • hash
    • hugo
    • images
    • inflect
    • js
    • lang
    • math
    • openapi3
    • os
    • partials
    • path
    • reflect
    • resources
    • safe
    • strings
    • templates
    • time
    • transform
    • urls
  • 方法
    • 本节内容
    • Duration
    • Menu
    • 菜单项
    • 页面
    • 分页器
    • 页面集
    • 资源
    • 短代码
    • 站点
    • 分类
    • 时间
  • 渲染钩子
    • 本节内容
    • 简介
    • 块引用
    • 代码块
    • 标题
    • 图像
    • 链接
    • 直通
    • 表格
  • 短代码
    • 本节内容
    • 评论
    • 详情
    • 图例
    • Gist
    • 高亮
    • Instagram
    • Param
    • QR
    • Ref
    • Relref
    • Vimeo
    • X
    • YouTube
  • Hugo 模块
    • 本节内容
    • 配置 Hugo 模块
    • 使用 Hugo 模块
    • 主题组件
  • Hugo Pipes
    • 本节内容
    • 简介
    • 将 Sass 转译为 CSS
    • PostCSS
    • PostProcess
    • JavaScript 构建
    • 资源压缩
    • 连接资源
    • 指纹和 SRI 哈希
    • 从字符串创建资源
    • 从模板创建资源
  • CLI
  • 问题排查
    • 本节内容
    • 审计
    • 日志记录
    • 检查
    • 弃用
    • 性能
    • 常见问题
  • 开发者工具
    • 本节内容
    • 编辑器插件
    • 前端
    • 搜索
    • 迁移
    • 其他项目
  • 托管和部署
    • 本节内容
    • Hugo Deploy
    • 使用 Rclone 部署
    • 使用 Rsync 部署
    • 在 21YunBox 上托管
    • 在 AWS Amplify 上托管
    • 在 Azure 静态 Web 应用上托管
    • 在 Cloudflare Pages 上托管
    • 在 Firebase 上托管
    • 在 GitHub Pages 上托管
    • 在 GitLab Pages 上托管
    • 在 KeyCDN 上托管
    • 在 Netlify 上托管
    • 在 Render 上托管
  • 贡献
    • 本节内容
    • 开发
    • 文档
    • 主题
  • 维护
内容管理

URL 管理

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

概述

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

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

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

前言

slug

在前言中设置 slug 可以覆盖路径的最后一段。 slug 值不影响章节页面。

content/posts/post-1.md
     
---
slug: my-first-post
title: My First Post
---
+++
slug = 'my-first-post'
title = 'My First Post'
+++
{
   "slug": "my-first-post",
   "title": "My First Post"
}

生成的 URL 将是

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

url

在前言中设置 url 可以覆盖整个路径。 将此用于常规页面或章节页面。

Hugo 不会清理 url 前言字段,允许您生成

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

如果在前言中同时设置了 slug 和 url,则 url 值优先。

包含冒号

v0.136.0 新增

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

例如,使用以下前言

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

生成的 URL 将是

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

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

文件扩展名

使用以下前言

content/posts/post-1.md
     
---
title: My First Article
url: articles/my-first-article
---
+++
title = 'My First Article'
url = 'articles/my-first-article'
+++
{
   "title": "My First Article",
   "url": "articles/my-first-article"
}

生成的 URL 将是

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

如果包含文件扩展名

content/posts/post-1.md
     
---
title: My First Article
url: articles/my-first-article.html
---
+++
title = 'My First Article'
url = 'articles/my-first-article.html'
+++
{
   "title": "My First Article",
   "url": "articles/my-first-article.html"
}

生成的 URL 将是

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

前导斜杠

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

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

前言中的 Permalink 标记

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
在 front matter date 字段中定义的 4 位数年份。
:month
在 front matter date 字段中定义的 2 位数月份。
:monthname
在 front matter date 字段中定义的月份名称。
:day
在 front matter date 字段中定义的 2 位数日期。
:weekday
在 front matter date 字段中定义的 1 位数星期几(星期日 = 0)。
:weekdayname
在 front matter date 字段中定义的星期几名称。
:yearday
在 front matter date 字段中定义的 1 到 3 位数年份中的第几天。
:section
内容的节。
:sections
内容的节层次结构。您可以使用 切片语法 选择节::sections[1:] 包括除第一个之外的所有节,:sections[:last] 包括除最后一个之外的所有节,:sections[last] 仅包括最后一个节,:sections[1:2] 包括第 2 和第 3 个节。请注意,此切片访问不会抛出任何越界错误,因此您不必非常精确。
:title
在 front matter 中定义的标题,否则为自动标题。Hugo 会为没有文件支持的节、分类法和术语页面自动生成标题。
:slug
在 front matter 中定义的 slug,否则为在 front matter 中定义的标题,否则为自动标题。Hugo 会为没有文件支持的节、分类法和术语页面自动生成标题。
:filename
内容的无扩展名文件名,适用于 page 页面类型。
:slugorfilename
在 front 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(带有前导斜杠)。然后,它会将 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 转换为相对于当前页面。

例如,在渲染 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 模板,请将 源代码复制到 layouts 目录中具有相同名称的文件中。该模板接收以下上下文

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

另请参阅

  • 前言
  • 组织
  • 文档
  • 原型
  • 配置

在此页面上

  • 概述
  • 前言
  • 站点配置
  • 别名
上次更新时间:2025 年 1 月 16 日:将目录名称、文件名和文件路径格式化为代码 (8051ff818)
改进此页面
由 Hugo 作者
Hugo Logo
  • 提交问题
  • 获取帮助
  • @GoHugoIO
  • @spf13
  • @bepsays

Netlify badge

 

Hugo 赞助商

贵公司?
 

Hugo 徽标的版权归 Steve Francia 2013–2025 所有。

Hugo 地鼠基于 Renée French 的原创作品。

  • 新闻
  • 文档
  • 主题
  • 社区
  • GitHub
  • 关于
  • 安装
  • 入门
  • 快速参考
  • 内容管理
  • 模板
  • 函数
  • 方法
  • 渲染钩子
  • 短代码
  • Hugo 模块
  • Hugo Pipes
  • CLI
  • 问题排查
  • 开发者工具
  • 托管和部署
  • 贡献
  • 维护