介紹

使用文件、目錄和環境變量配置您的站點。

合理的默認值

Hugo 提供許多配置選項，但其默認值通常已足夠。新站點只需要這些設置：

baseURL: https://example.org/
languageCode: en-us
title: 我的新 Hugo 站點

baseURL = 'https://example.org/'
languageCode = 'en-us'
title = '我的新 Hugo 站點'

{
   "baseURL": "https://example.org/",
   "languageCode": "en-us",
   "title": "我的新 Hugo 站點"
}

只定義偏離默認值的設置。較小的配置文件更易於閱讀、理解和調試。保持配置簡潔。

最好的配置文件是簡短的配置文件。

配置文件

在項目目錄的根目錄中創建站點配置文件，命名為 hugo.toml、hugo.yaml 或 hugo.json，優先級依次遞減。

my-project/
└── hugo.toml

對於 v0.109.0 及更早版本，站點配置文件名為 config。雖然您仍然可以使用此名稱，但建議改用更新的命名約定 hugo。

一個簡單示例：

baseURL: https://example.org/
languageCode: en-us
params:
  contact:
    email: info@example.org
    phone: +1 202-555-1212
  subtitle: 地球上最好的五金
title: ABC 五金公司

baseURL = 'https://example.org/'
languageCode = 'en-us'
title = 'ABC 五金公司'
[params]
  subtitle = '地球上最好的五金'
  [params.contact]
    email = 'info@example.org'
    phone = '+1 202-555-1212'

{
   "baseURL": "https://example.org/",
   "languageCode": "en-us",
   "params": {
      "contact": {
         "email": "info@example.org",
         "phone": "+1 202-555-1212"
      },
      "subtitle": "地球上最好的五金"
   },
   "title": "ABC 五金公司"
}

要使用不同的配置文件構建站點，使用 --config 標志：

hugo --config other.toml

合並兩個或多個配置文件，從左到右優先級遞增：

hugo --config a.toml,b.yaml,c.json

查看每種文件格式的規范：TOML、YAML 和 JSON。

配置目錄

與使用單個站點配置文件不同，您可以按環境、根配置鍵和語言拆分配置。例如：

my-project/
└── config/
    ├── _default/
    │   ├── hugo.toml
    │   ├── menus.en.toml
    │   ├── menus.de.toml
    │   └── params.toml
    └── production/
        └── params.toml

根配置鍵是 HTTPCache, build, caches, contentTypes, deployment, frontmatter, imaging, languages, markup, mediaTypes, menus, minify, module, outputFormats, outputs, page, pagination, params, permalinks, privacy, related, roles, security, segments, server, services, sitemap, taxonomies, uglyURLs, and versions。

您必須在根配置文件中定義 cascade 表。您不能在專用文件中定義 cascade 表。詳見 issue #12899。

省略根鍵

當按根鍵拆分配置時，在組件文件中省略根鍵。例如，這些是等效的：

params:
  foo: bar

[params]
  foo = 'bar'

{
   "params": {
      "foo": "bar"
   }
}

foo: bar

foo = 'bar'

{
   "foo": "bar"
}

遞歸解析

Hugo 遞歸解析 config 目錄，允許您將文件組織到子目錄中。例如：

my-project/
└── config/
    └── _default/
        ├── navigation/
        │   ├── menus.de.toml
        │   └── menus.en.toml
        └── hugo.toml

示例

my-project/
└── config/
    ├── _default/
    │   ├── hugo.toml
    │   ├── menus.en.toml
    │   ├── menus.de.toml
    │   └── params.toml
    ├── production/
    │   ├── hugo.toml
    │   └── params.toml
    └── staging/
        ├── hugo.toml
        └── params.toml

考慮到上述結構，當運行 hugo --environment staging 時，Hugo 將使用 config/_default 中的每個設置，並將 staging 的設置合並到其上。

讓我們舉個例子來更好地理解這一點。假設您的網站使用 Google Analytics。這需要在站點配置中指定 Google 標簽 ID：

services:
  googleAnalytics:
    ID: G-XXXXXXXXX

[services]
  [services.googleAnalytics]
    ID = 'G-XXXXXXXXX'

{
   "services": {
      "googleAnalytics": {
         "ID": "G-XXXXXXXXX"
      }
   }
}

現在考慮以下場景：

運行 hugo server 時，您不想加載分析代碼。
您想為生產和暫存環境使用不同的 Google 標簽 ID。例如：
- G-PPPPPPPPP 用於生產環境
- G-SSSSSSSSS 用於暫存環境

要滿足這些需求，請按以下方式配置您的站點：

config/_default/hugo.toml
- 排除 services.googleAnalytics 部分。這將防止在運行 hugo server 時加載分析代碼。
- 默認情況下，Hugo 在運行 hugo server 時將 environment 設置為 development。在沒有 config/development 目錄的情況下，Hugo 使用 config/_default 目錄。
config/production/hugo.toml
- 僅包含此部分：
  hugo.
  services: googleAnalytics: ID: G-PPPPPPPPP
  [services] [services.googleAnalytics] ID = 'G-PPPPPPPPP'
  { "services": { "googleAnalytics": { "ID": "G-PPPPPPPPP" } } }
- 您不需要在此文件中包含其他參數。只包含特定於生產環境的參數。Hugo 會將這些參數與默認配置合並。
- 默認情況下，Hugo 在運行 hugo 時將 environment 設置為 production。分析代碼將使用 G-PPPPPPPPP 標簽 ID。
config/staging/hugo.toml
- 僅包含此部分：
  hugo.
  services: googleAnalytics: ID: G-SSSSSSSSS
  [services] [services.googleAnalytics] ID = 'G-SSSSSSSSS'
  { "services": { "googleAnalytics": { "ID": "G-SSSSSSSSS" } } }
- 您不需要在此文件中包含其他參數。只包含特定於暫存環境的參數。Hugo 會將這些參數與默認配置合並。
- 要構建暫存站點，運行 hugo --environment staging。分析代碼將使用 G-SSSSSSSSS 標簽 ID。

合並配置設置

Hugo 合並來自主題和模塊的配置設置，優先使用項目自己的設置。給定這個簡化的項目結構，包含兩個主題：

project/
├── themes/
│   ├── theme-a/
│   │   └── hugo.toml
│   └── theme-b/
│       └── hugo.toml
└── hugo.toml

和這個項目級配置：

baseURL: https://example.org/
languageCode: en-us
theme:
- theme-a
- theme-b
title: 我的新 Hugo 站點

baseURL = 'https://example.org/'
languageCode = 'en-us'
theme = ['theme-a', 'theme-b']
title = '我的新 Hugo 站點'

{
   "baseURL": "https://example.org/",
   "languageCode": "en-us",
   "theme": [
      "theme-a",
      "theme-b"
   ],
   "title": "我的新 Hugo 站點"
}

Hugo 按此順序合並設置：

項目配置（項目根目錄中的 hugo.toml）
theme-a 配置
theme-b 配置

每個頂級配置鍵中的 _merge 設置控制哪些設置被合並以及如何合並。

_merge 的值可以是以下之一：

none: 不合並。
shallow: 僅為新鍵添加值。
deep: 為新鍵添加值，合並現有鍵。

請注意，您不需要像下面的默認設置中那樣冗長；如果未設置，較高的 _merge 值將被繼承。

build:
  _merge: none
caches:
  _merge: none
cascade:
  _merge: none
contenttypes:
  _merge: none
deployment:
  _merge: none
frontmatter:
  _merge: none
httpcache:
  _merge: none
imaging:
  _merge: none
languages:
  _merge: none
  en:
    _merge: none
    menus:
      _merge: shallow
    params:
      _merge: deep
markup:
  _merge: none
mediatypes:
  _merge: shallow
menus:
  _merge: shallow
minify:
  _merge: none
module:
  _merge: none
outputformats:
  _merge: shallow
outputs:
  _merge: none
page:
  _merge: none
pagination:
  _merge: none
params:
  _merge: deep
permalinks:
  _merge: none
privacy:
  _merge: none
related:
  _merge: none
roles:
  _merge: none
security:
  _merge: none
segments:
  _merge: none
server:
  _merge: none
services:
  _merge: none
sitemap:
  _merge: none
taxonomies:
  _merge: none
versions:
  _merge: none

[build]
  _merge = 'none'
[caches]
  _merge = 'none'
[cascade]
  _merge = 'none'
[contenttypes]
  _merge = 'none'
[deployment]
  _merge = 'none'
[frontmatter]
  _merge = 'none'
[httpcache]
  _merge = 'none'
[imaging]
  _merge = 'none'
[languages]
  _merge = 'none'
  [languages.en]
    _merge = 'none'
    [languages.en.menus]
      _merge = 'shallow'
    [languages.en.params]
      _merge = 'deep'
[markup]
  _merge = 'none'
[mediatypes]
  _merge = 'shallow'
[menus]
  _merge = 'shallow'
[minify]
  _merge = 'none'
[module]
  _merge = 'none'
[outputformats]
  _merge = 'shallow'
[outputs]
  _merge = 'none'
[page]
  _merge = 'none'
[pagination]
  _merge = 'none'
[params]
  _merge = 'deep'
[permalinks]
  _merge = 'none'
[privacy]
  _merge = 'none'
[related]
  _merge = 'none'
[roles]
  _merge = 'none'
[security]
  _merge = 'none'
[segments]
  _merge = 'none'
[server]
  _merge = 'none'
[services]
  _merge = 'none'
[sitemap]
  _merge = 'none'
[taxonomies]
  _merge = 'none'
[versions]
  _merge = 'none'

{
   "build": {
      "_merge": "none"
   },
   "caches": {
      "_merge": "none"
   },
   "cascade": {
      "_merge": "none"
   },
   "contenttypes": {
      "_merge": "none"
   },
   "deployment": {
      "_merge": "none"
   },
   "frontmatter": {
      "_merge": "none"
   },
   "httpcache": {
      "_merge": "none"
   },
   "imaging": {
      "_merge": "none"
   },
   "languages": {
      "_merge": "none",
      "en": {
         "_merge": "none",
         "menus": {
            "_merge": "shallow"
         },
         "params": {
            "_merge": "deep"
         }
      }
   },
   "markup": {
      "_merge": "none"
   },
   "mediatypes": {
      "_merge": "shallow"
   },
   "menus": {
      "_merge": "shallow"
   },
   "minify": {
      "_merge": "none"
   },
   "module": {
      "_merge": "none"
   },
   "outputformats": {
      "_merge": "shallow"
   },
   "outputs": {
      "_merge": "none"
   },
   "page": {
      "_merge": "none"
   },
   "pagination": {
      "_merge": "none"
   },
   "params": {
      "_merge": "deep"
   },
   "permalinks": {
      "_merge": "none"
   },
   "privacy": {
      "_merge": "none"
   },
   "related": {
      "_merge": "none"
   },
   "roles": {
      "_merge": "none"
   },
   "security": {
      "_merge": "none"
   },
   "segments": {
      "_merge": "none"
   },
   "server": {
      "_merge": "none"
   },
   "services": {
      "_merge": "none"
   },
   "sitemap": {
      "_merge": "none"
   },
   "taxonomies": {
      "_merge": "none"
   },
   "versions": {
      "_merge": "none"
   }
}

環境變量

您還可以使用操作系統環境變量配置設置：

export HUGO_BASEURL=https://example.org/
export HUGO_ENABLEGITINFO=true
export HUGO_ENVIRONMENT=staging
hugo

上述設置 baseURL、enableGitInfo 和 environment 配置選項，然後構建您的站點。

環境變量優先於配置文件中設置的值。這意味著如果您同時使用環境變量和配置文件設置配置值，將使用環境變量中的值。

環境變量通過在各自的配置和工作流文件中直接設置值，簡化了 CI/CD 平台的配置。

環境變量名必須以 HUGO_ 為前綴。

要設置自定義站點參數，以 HUGO_PARAMS_ 為前綴。

對於 snake_case 變量名，標准的 HUGO_ 前綴不起作用。Hugo 從 HUGO 之後的第一個字符推斷分隔符。這允許使用任何允許的分隔符進行變體，如 HUGOxPARAMSxAPI_KEY=abcdefgh。

除了配置標准設置外，環境變量還可用於覆蓋某些內部設置的默認值：

DART_SASS_BINARY: (string) Dart Sass 可執行文件的絕對路徑。默認情況下，Hugo 在 PATH 環境變量的每個路徑中搜索可執行文件。
HUGO_FILE_LOG_FORMAT: (string) 報告錯誤時或在短代碼或 Markdown 渲染鉤子中調用 Position 方法時顯示的文件路徑、行號和列號的格式字符串。有效標記是 :file、:line 和 :col。默認值是 :file::line::col。
HUGO_MEMORYLIMIT: (int) Hugo 渲染站點時可以使用的最大系統內存量（以 GB 為單位）。默認值是總系統內存的 25%。請注意，HUGO_MEMORYLIMIT 是一個"盡力而為"的設置。不要期望 Hugo 用只有 1 GB 內存構建一百萬個頁面。您可以通過使用 hugo --logLevel info 構建並查找 dynacache 標簽來了解此設置在構建過程中的行為。
HUGO_NUMWORKERMULTIPLIER: (int) 並行處理中使用的工作線程數。默認值是邏輯 CPU 的數量。

當前配置

使用以下命令顯示完整的站點配置：

hugo config

使用以下命令顯示特定的配置設置：

hugo config | grep [key]

使用以下命令顯示配置的文件掛載：

hugo config mounts

Last updated: January 1, 0001

Improve this page