介绍

使用文件、目录和环境变量配置您的站点。

合理的默认值

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