Hugo URL 管理

概述

默認情況下，當 Hugo 渲染頁面時，生成的 URL 匹配 content 目錄內的文件路徑。例如：

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

你可以使用 front matter 值和站點配置選項更改 URL 的結構和外觀。

Front matter

slug

在 front matter 中設置 slug 以覆蓋路徑的最後一段。此 front matter 字段不適用於 home、section、taxonomy 或 term 頁面。

---
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

在 front matter 中設置 url 以覆蓋整個路徑。對常規頁面或 section 頁面使用此字段。

如果你在 front matter 中同時設置 slug 和 url，url 值優先。

包含冒號

如果你需要在 url front matter 字段中包含冒號，使用反斜槓字符轉義。如果將字符串包裹在單引號中，使用一個反斜槓；如果將字符串包裹在雙引號中，使用兩個反斜槓。對於 YAML front matter，如果省略引號，使用單個反斜槓。

例如，使用此 front matter：

---
title: Example
url: 'my\:example'
---

+++
title = 'Example'
url = 'my\:example'
+++

{
   "title": "Example",
   "url": "my\\:example"
}

生成的 URL 將是：

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

如上所述，這在 Windows 上將失敗，因為冒號（:）是保留字符。

文件擴展名

使用此 front matter：

---
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/

如果你包含文件擴展名：

---
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 加上語言前綴。

front matter 中的永久鏈接令牌

你還可以在設置 url 值時使用令牌。這通常在 cascade 部分中使用：

---
cascade:
- url: /:sections[last]/:slug
title: Bar
---

+++
title = 'Bar'
[[cascade]]
  url = '/:sections[last]/:slug'
+++

{
   "cascade": [
      {
         "url": "/:sections[last]/:slug"
      }
   ],
   "title": "Bar"
}

使用以下任何令牌：

: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

內容的部分。

:sectionslug

New in v0.149.0

使用 slugified 部分名稱的內容部分。slugified 部分名稱是 front matter 中定義的 slug，否則是 front matter 中定義的 title，否則是自動標題。

:sections

內容的部分層次結構。您可以使用 slice 語法 選擇部分：:sections[1:] 包括除第一個之外的所有部分，:sections[:last] 包括除最後一個之外的所有部分，:sections[last] 僅包括最後一個，:sections[1:2] 包括第 2 和第 3 部分。請注意，此 slice 訪問不會拋出任何越界錯誤，因此您不必精確。

:sectionslugs

New in v0.149.0

使用 slugified 部分名稱的內容部分層次結構。slugified 部分名稱是 front matter 中定義的 slug，否則是 front matter 中定義的 title，否則是自動標題。您可以使用 slice 語法 選擇部分：:sectionslugs[1:] 包括除第一個之外的所有部分，:sectionslugs[:last] 包括除最後一個之外的所有部分，:sectionslugs[last] 僅包括最後一個，:sectionslugs[1:2] 包括第 2 和第 3 部分。請注意，此 slice 訪問不會拋出任何越界錯誤，因此您不必精確。

:title

front matter 中定義的 title，否則是自動標題。Hugo 為沒有文件支持的部分、分類法和術語頁面自動生成標題。

:slug

front matter 中定義的 slug，否則是 front matter 中定義的 title，否則是自動標題。Hugo 為沒有文件支持的部分、分類法和術語頁面自動生成標題。

:filename

內容的文件名（不含擴展名），適用於 page 頁面類型。

Deprecated in v0.144.0

:filename 標記已棄用。請改用 :contentbasename。

:slugorfilename

front matter 中定義的 slug，否則是內容的文件名（不含擴展名），適用於 page 頁面類型。

Deprecated in v0.144.0

:slugorfilename 標記已棄用。請改用 :slugorcontentbasename。

:contentbasename

New in v0.144.0

內容基本名稱。

:slugorcontentbasename

New in v0.144.0

front matter 中定義的 slug，否則是 內容基本名稱。

對於時間相關的值，您還可以使用 Go time 包 中定義的布局字符串組件。例如：

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

[permalinks]
  posts = '/:06/:1/:2/:title/'

{
   "permalinks": {
      "posts": "/:06/:1/:2/:title/"
   }
}

站點配置

永久鏈接

請參閱 configure permalinks。

外觀

請參閱 configure ugly URLs。

後處理

Hugo 提供兩個互斥的配置選項，在渲染頁面 之後 更改 URL。

規范 URL

如果啟用，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 屬性。如上所述，這是一個遺留配置選項，可能會在未來版本中刪除。

啟用：

canonifyURLs: true

canonifyURLs = true

{
   "canonifyURLs": true
}

相對 URL

如果啟用，Hugo 在渲染頁面 之後 執行搜索和替換。它搜索與 action、href、src、srcset 和 url 屬性關聯的站點相對 URL（那些有前導斜槓的 URL）。然後將 URL 轉換為相對於當前頁面。

例如，渲染 content/posts/post-1 時：

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

這是一種不完美的粗暴方法，可能影響內容以及 HTML 屬性。如上所述，除非你正在創建無服務器站點，否則不要啟用此選項。

啟用：

relativeURLs: true

relativeURLs = true

{
   "relativeURLs": true
}

別名

別名允許你將舊 URL 重定向到新 URL。這對於防止鏈接失效並確保在你重命名或移動內容時現有書簽或外部鏈接繼續有效至關重要。

定義別名

要為頁面添加重定向，在 front matter 中的 aliases 字段列出以前的路徑。Hugo 在構建過程中將這些解析為 server-relative 路徑，考慮 baseURL 和 content dimension 前綴，如語言、角色或版本。

---
aliases:
- /old-url
- old-name
- ../old/path
date: '2025-02-02'
title: Example 1
---

+++
aliases = ['/old-url', 'old-name', '../old/path']
date = 2025-02-02
title = 'Example 1'
+++

{
   "aliases": [
      "/old-url",
      "old-name",
      "../old/path"
   ],
   "date": "2025-02-02",
   "title": "Example 1"
}

如上面的示例所示，你可以使用 site-relative 路徑或 page-relative 路徑。頁面相對路徑也可以包括目錄遍歷。使用文件 content/examples/example-1.en.md 作為參考點，以下是 Hugo 如何解釋這些不同路徑類型：

重定向方法

根據你的托管環境和個人偏好，有兩種方法實現別名：客戶端重定向和服務器端重定向。

客戶端重定向

默認情況下，Hugo 使用客戶端重定向，為每個別名生成一個小 HTML 文件。此文件包含一個 meta http-equiv="refresh" 標簽，指示瀏覽器導航到新 URL。這種方法適用於所有托管提供商。

使用此方法時，Hugo 在每個別名位置創建物理目錄和 index.html 文件。例如，如果 content/posts/new.md 的頁面有一個頁面相對別名 old-path，則在 public/posts/old-path/index.html 生成文件。

除非你提供自定義布局，否則 Hugo 使用其 embedded alias template 生成重定向文件：

<!DOCTYPE html>
<html lang="{{ site.Language.LanguageCode }}">
  <head>
    <title>{{ .Permalink }}</title>
    {{ with .OutputFormats.Canonical }}<link rel="{{ .Rel }}" href="{{ .Permalink }}">{{ end }}
    <meta charset="utf-8">
    <meta http-equiv="refresh" content="0; url={{ .Permalink }}">
  </head>
</html>

要覆蓋此，在 layouts 目錄中創建名為 alias.html 的文件。此自定義模板可以訪問以下上下文：

Permalink

(string) 目標頁面的絕對 URL。

Page

(page.Page) 目標的完整 Page 對象。

服務器端重定向

或者，你可以使用 Page 對象上的 Aliases 方法實現服務器端重定向，生成 Web 服務器處理的單個配置文件。此方法更有效，因為重定向發生在 HTTP 標頭級別，在任何頁面內容處理之前，而 meta refresh 需要瀏覽器下載並解析 HTML 主體然後操作。此外，服務器端重定向改善構建和部署時間，因為 Hugo 不需要為每個別名寫入物理目錄和 HTML 文件。

要實現此，你通常創建單個模板來為你的特定主機或服務器生成必要的規則。常見示例包括：

• 用於托管服務（如 Cloudflare、GitLab Pages 和 Netlify）的 _redirects 文件。
• 用於 Web 服務器（如 Apache 和 LiteSpeed）的 .htaccess 文件。

請參閱 Aliases 方法頁面，了解如何遍歷頁面生成這些規則的完整示例。

如果你實現服務器端重定向，你應該通過在站點配置中將 disableAliases 設置為 true 來禁用單個 HTML 文件的生成。此設置僅防止物理 HTML 文件的生成；Aliases 方法在 Page 對象上仍可用於你的配置模板。