配置 Hugo

配置文件

Hugo 使用 hugo.toml, hugo.yaml, 或者 hugo.json（如果位于站点根目录中找到）作为默认的站点配置文件。

用户可以选择使用命令行的 --config 开关来覆盖这个默认值，一个或多个站点配置文件。

示例：

hugo --config debugconfig.toml
hugo --config a.toml,b.toml,c.toml

hugo.toml 与 config.toml

在 Hugo 0.110.0 版本中，我们将默认配置基本文件名更改为 hugo，例如 hugo.toml。但我们仍然可以找到 config.toml等文件，但我们建议您最终将其重命名（但如果您想要支持旧版本的 Hugo，则需要等待）。我们这样做的主要原因是使代码编辑器和构建工具更容易识别这个文件，知道它是一个 Hugo 配置文件和项目。

配置目录

除了使用单个站点配置文件外，您可以使用 configDir 目录（默认为 config/）来更轻松地组织和管理特定于环境的设置。

每个文件都代表一个配置根对象，例如 [Params] 对应于 params.toml，[Menu] 对应于 menu(s).toml，[Languages] 对应于 languages.toml 等等…
每个文件的内容必须是顶级的，例如：

hugo.

Params:
  foo: bar

[Params]
  foo = 'bar'

{
   "Params": {
      "foo": "bar"
   }
}

params.

foo: bar

foo = 'bar'

{
   "foo": "bar"
}

每个目录包含一组包含特定环境设置的文件。
文件可以本地化为特定语言。

├── config
│   ├── _default
│   │   ├── hugo.toml
│   │   ├── languages.toml
│   │   ├── menus.en.toml
│   │   ├── menus.zh.toml
│   │   └── params.toml
│   ├── production
│   │   ├── hugo.toml
│   │   └── params.toml
│   └── staging
│       ├── hugo.toml
│       └── params.toml

考虑上面的结构，当运行 hugo --environment staging 时，Hugo 将使用 config/_default 中的所有设置，并将 staging 的设置与之合并。

让我们通过一个示例了解这个设置。假设您在您的网站中使用 Google Analytics。这要求您在站点配置中指定一个 Google 标签 ID：

hugo.

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 server 时，Hugo 将其 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。

从主题合并配置

_merge 的配置值可以是以下之一：

none: 表示不合并。
shallow: 只添加新键的值。
deep: 添加新键的值，并合并已有键的值。

请注意，您不需要像下面的默认设置那样那么冗长；如果没有设置，则会继承更高层次的 _merge 值。

hugo.

build:
  _merge: none
caches:
  _merge: none
cascade:
  _merge: none
deployment:
  _merge: none
frontmatter:
  _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
params:
  _merge: deep
permalinks:
  _merge: none
privacy:
  _merge: none
related:
  _merge: none
security:
  _merge: none
server:
  _merge: none
services:
  _merge: none
sitemap:
  _merge: none
taxonomies:
  _merge: none

[build]
  _merge = 'none'
[caches]
  _merge = 'none'
[cascade]
  _merge = 'none'
[deployment]
  _merge = 'none'
[frontmatter]
  _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'
[params]
  _merge = 'deep'
[permalinks]
  _merge = 'none'
[privacy]
  _merge = 'none'
[related]
  _merge = 'none'
[security]
  _merge = 'none'
[server]
  _merge = 'none'
[services]
  _merge = 'none'
[sitemap]
  _merge = 'none'
[taxonomies]
  _merge = 'none'

{
   "build": {
      "_merge": "none"
   },
   "caches": {
      "_merge": "none"
   },
   "cascade": {
      "_merge": "none"
   },
   "deployment": {
      "_merge": "none"
   },
   "frontmatter": {
      "_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"
   },
   "params": {
      "_merge": "deep"
   },
   "permalinks": {
      "_merge": "none"
   },
   "privacy": {
      "_merge": "none"
   },
   "related": {
      "_merge": "none"
   },
   "security": {
      "_merge": "none"
   },
   "server": {
      "_merge": "none"
   },
   "services": {
      "_merge": "none"
   },
   "sitemap": {
      "_merge": "none"
   },
   "taxonomies": {
      "_merge": "none"
   }
}

所有配置设置

以下是 Hugo 定义的所有变量列表。用户可以选择在站点配置文件中覆盖这些值。

archetypeDir

默认值： “archetypes”

Hugo 查找原型文件（内容模板）的目录。Also see Module Mounts Config for an alternative way to configure this directory (from Hugo 0.56).

assetDir

默认值： “assets”

Hugo 查找用于Hugo Pipes的资源文件的目录。Also see Module Mounts Config for an alternative way to configure this directory (from Hugo 0.56).

baseURL

已发布站点的绝对 URL（协议、主机、路径和尾随斜杠）（例如，https://www.example.org/docs/）。

build

参见配置构建。

buildDrafts (false)

默认值： false

构建时包含草稿。

buildExpired

默认值： false

包含已过期的内容。

buildFuture

默认值： false

包含发布日期在未来的内容。

caches

参见配置文件缓存。

cascade

将默认配置值（页首元数据）传递给内容树中的页面。站点配置中的选项与页面页首元数据中的选项相同，参见Front Matter Cascade。

canonifyURLs

默认值： false

启用后，将相对 URL 转换为绝对 URL。参见详细信息。

cleanDestinationDir

默认值： false

在构建时，从目标中删除在静态目录中找不到的文件。

contentDir

默认值： “content”

Hugo 读取内容文件的目录。Also see Module Mounts Config for an alternative way to configure this directory (from Hugo 0.56).

copyright

默认值： ""

dataDir

默认值： “data”

Hugo 读取数据文件的目录。Also see Module Mounts Config for an alternative way to configure this directory (from Hugo 0.56).

defaultContentLanguage

默认值： “en”

没有语言标识的内容将默认为该语言。

defaultContentLanguageInSubdir

默认值： false

在子目录中渲染默认内容语言，例如 content/en/。然后站点根目录 / 将重定向到 /en/。

disableAliases

默认值： false

禁用别名重定向的生成。请注意，即使 disableAliases 被设置，别名本身也会保留在页面上。这样做的动机是能够使用自定义输出格式在 .htaccess、Netlify 的 _redirects 文件或类似文件中生成 301 重定向。

disableHugoGeneratorInject

默认值： false

Hugo 默认在 HTML 的首页的头部插入一个生成器元标记。您可以关闭它，但是我们非常希望您不要这样做，因为这是观察 Hugo 受欢迎程度的一种好方法。

disableKinds

默认值： []

启用对指定 Kind 的所有页面的禁用。列表中允许的值有：“page”、“home”、“section”、“taxonomy”、“term”、“RSS”、“sitemap”、“robotsTXT”、“404”。

disableLiveReload

默认值： false

禁用浏览器窗口的自动刷新。

disablePathToLower

默认值： false

不要将 URL/路径转换为小写。

enableEmoji

默认值： false

在页面内容中启用 Emoji 表情符号的支持；参见表情符号简明参考指南。

enableGitInfo

默认值： false

为每个页面启用 .GitInfo 对象（如果 Hugo 站点经由 Git 进行版本控制）。这将使用该内容文件的最后的 git 提交日期来更新每个页面的 Lastmod 参数。

enableInlineShortcodes

默认值： false

启用内联段代码支持。参见内联段代码。

enableMissingTranslationPlaceholders

默认值： false

如果找不到翻译，则显示一个占位符，而不是默认值或空字符串。

enableRobotsTXT

默认值： false

启用生成 robots.txt 文件。

frontmatter

参见配置页面元数据。

hasCJKLanguage

默认值： false

如果为 true，则自动检测中文/日语/韩语语言的内容。这会使 .Summary 和 .WordCount 对于 CJK 语言表现正确。

imaging

参见图像处理配置。

languageCode

默认值： ""

RFC 5646 定义的语言标签。此值用于填充：

内部RSS 模板中的 <language> 元素。
内部alias 模板中 <html> 元素的 lang 属性。

module

模块配置参见模块配置。

newContentEditor

默认值： ""

创建新内容使用的编辑器。

noChmod

默认值： false

不同步文件的权限模式。

noTimes

默认值： false

不同步文件的修改时间。

outputFormats

参见配置输出格式。

paginate

默认值： 10

pagination 中每页的元素默认数量。

paginatePath

默认值： “page”

用于分页的路径元素（https://example.org/page/2）。

permalinks

参见内容管理。

pluralizeListTitles

默认值： true

对列表中的标题进行复数化处理。

publishDir

默认值： “public”

Hugo 将编写最终的静态站点的目录（HTML 文件等）。

参见相关内容。

relativeURLs

默认值： false

启用此项，使所有相对 URL 基于内容根。请注意，这不会影响绝对 URL。参见详细信息。

refLinksErrorLevel

默认值： “ERROR”

使用 ref 或 relref 解析页面链接时，如果无法解析链接，则将使用此记录级别进行记录。有效值为 ERROR（默认）或 WARNING。任何 ERROR 都会导致构建失败（exit -1）。

refLinksNotFoundURL

用作占位符的 URL，当在 ref 或 relref 中找不到页面引用时。使用原样。

removePathAccents

默认值： false

从内容路径中删除组合字符中的非间隔标记。

content/post/hügó.md → https://example.org/post/hugo/

rssLimit

默认值： -1（无限制）

RSS feed 中的最大项目数。

sectionPagesMenu

参见导航菜单。

security

参见安全策略。

sitemap

默认的站点地图配置。

summaryLength

默认值： 70

自动摘要中显示的文字长度（单词）.Summary。

taxonomies

参见配置分类法。

theme

: 导入主题的配置，请参见模块配置。

themesDir

默认值： “themes”

Hugo 读取主题的目录。

timeout

默认值： “30s”

生成页面内容的超时时间，指定为持续时间或秒数。*注意：*这用来跳过递归内容生成。如果您的页面生成缓慢（例如因为它们需要进行大量图像处理或依赖于远程内容），则可能需要提高此限制。

timeZone

时区（或位置），例如 Europe/Oslo，用于解析没有此信息的页首日期或者 time 函数。有效值列表可能因系统而异，但应该包括 UTC、Local 和 IANA 时区数据库中的任何位置。

title

站点标题。

titleCaseStyle

默认值： “ap”

参见配置标题格式。

uglyURLs

默认值： false

启用时，创建的 URL 格式是 /filename.html 而不是 /filename/。

watch

默认值： false

监视文件系统的更改，必要时重新创建。

如果您在 *nix 机器上开发站点，以下是在命令行上查找配置选项的一个便捷方法：

cd ~/sites/yourhugosite
hugo config | grep emoji

这将显示如下输出

enableemoji: true

配置构建

build 配置部分包含了全局构建相关的配置选项。

hugo.

build:
  buildStats:
    disableClasses: false
    disableIDs: false
    disableTags: false
    enable: false
  cacheBusters:
  - source: assets/.*\.(js|ts|jsx|tsx)
    target: (js|scripts|javascript)
  - source: assets/.*\.(css|sass|scss)$
    target: (css|styles|scss|sass)
  - source: (postcss|tailwind)\.config\.js
    target: (css|styles|scss|sass)
  - source: assets/.*\.(.*)$
    target: $1
  noJSConfigInAssets: false
  useResourceCacheWhen: fallback

[build]
  noJSConfigInAssets = false
  useResourceCacheWhen = 'fallback'
  [build.buildStats]
    disableClasses = false
    disableIDs = false
    disableTags = false
    enable = false
[[build.cacheBusters]]
    source = 'assets/.*\.(js|ts|jsx|tsx)'
    target = '(js|scripts|javascript)'
[[build.cacheBusters]]
    source = 'assets/.*\.(css|sass|scss)$'
    target = '(css|styles|scss|sass)'
[[build.cacheBusters]]
    source = '(postcss|tailwind)\.config\.js'
    target = '(css|styles|scss|sass)'
[[build.cacheBusters]]
    source = 'assets/.*\.(.*)$'
    target = '$1'

{
   "build": {
      "buildStats": {
         "disableClasses": false,
         "disableIDs": false,
         "disableTags": false,
         "enable": false
      },
      "cacheBusters": [
         {
            "source": "assets/.*\\.(js|ts|jsx|tsx)",
            "target": "(js|scripts|javascript)"
         },
         {
            "source": "assets/.*\\.(css|sass|scss)$",
            "target": "(css|styles|scss|sass)"
         },
         {
            "source": "(postcss|tailwind)\\.config\\.js",
            "target": "(css|styles|scss|sass)"
         },
         {
            "source": "assets/.*\\.(.*)$",
            "target": "$1"
         }
      ],
      "noJSConfigInAssets": false,
      "useResourceCacheWhen": "fallback"
   }
}

buildStats: 当启用时，在项目根目录下创建一个 hugo_stats.json 文件。该文件包含了已发布站点中每个 HTML 元素的 class 属性、id 属性和标签的数组。在清理未使用的 CSS 时，可以将该文件作为数据源。也可以称此过程为修剪、清理或摇树。

通过 disableClasses、disableIDs 和 disableTags 键，可以从 hugo_stats.json 中排除 class 属性、id 属性或标签。

由于部分服务器构建的特性，在服务器运行时会添加新的 HTML 实体，但旧值只有在重新启动服务器或运行常规的 hugo 构建后才会被删除。

cachebusters: 请参阅配置缓存集装箱
noJSConfigInAssets: 关闭在 /assets 文件夹中写入一个 jsconfig.json 文件，该文件包含从 js.Build 中的导入映射。此文件旨在帮助在代码编辑器如 VS Code 中进行智能提示/导航。请注意，如果你不使用 js.Build，则不会写入任何文件。
useResourceCacheWhen: 何时使用 /resources/_gen 中的缓存资源进行 PostCSS 和 ToCSS。有效值为 never、always 和 fallback。最后一个值意味着如果 PostCSS/扩展版本不可用，则尝试使用缓存。

配置缓存集装箱

添加了 build.cachebusters 配置选项，以支持使用 Tailwind 3.x 的 JIT 编译器进行开发，一个 build 的配置可能如下所示:

hugo.

build:
  buildStats:
    enable: true
  cachebusters:
  - source: assets/watching/hugo_stats\.json
    target: styles\.css
  - source: (postcss|tailwind)\.config\.js
    target: css
  - source: assets/.*\.(js|ts|jsx|tsx)
    target: js
  - source: assets/.*\.(.*)$
    target: $1

[build]
  [build.buildStats]
    enable = true
[[build.cachebusters]]
    source = 'assets/watching/hugo_stats\.json'
    target = 'styles\.css'
[[build.cachebusters]]
    source = '(postcss|tailwind)\.config\.js'
    target = 'css'
[[build.cachebusters]]
    source = 'assets/.*\.(js|ts|jsx|tsx)'
    target = 'js'
[[build.cachebusters]]
    source = 'assets/.*\.(.*)$'
    target = '$1'

{
   "build": {
      "buildStats": {
         "enable": true
      },
      "cachebusters": [
         {
            "source": "assets/watching/hugo_stats\\.json",
            "target": "styles\\.css"
         },
         {
            "source": "(postcss|tailwind)\\.config\\.js",
            "target": "css"
         },
         {
            "source": "assets/.*\\.(js|ts|jsx|tsx)",
            "target": "js"
         },
         {
            "source": "assets/.*\\.(.*)$",
            "target": "$1"
         }
      ]
   }
}

上述代码中的一些重要点如下：writeStats = true，它会在每次构建时写入一个 hugo_stats.json 文件，其中包含在渲染输出中使用的 HTML 类等。对这个文件的更改将触发 styles.css 文件的重新构建。您还需要将 hugo_stats.json 添加到 Hugo 的服务器观察器中。有关运行示例，请参阅 Hugo Starter Tailwind Basic。

source: 正则表达式，匹配与 Hugo 中的一些虚拟组件目录相关的文件（通常是 assets/...）。
target: 正则表达式，匹配在 source 发生更改时应该过期的资源缓存项键。您可以在表达式中使用 source 中的匹配正则表达式组，例如 $1。

配置服务器

这仅适用于运行 hugo server 时，并且允许在开发过程中设置 HTTP 标头，这样您就可以测试您的内容安全策略等。配置格式与 Netlify 相匹配，并且使用稍微更强大的文件匹配:

hugo.

server:
  headers:
  - for: /**
    values:
      Content-Security-Policy: script-src localhost:1313
      Referrer-Policy: strict-origin-when-cross-origin
      X-Content-Type-Options: nosniff
      X-Frame-Options: DENY
      X-XSS-Protection: 1; mode=block

[server]
[[server.headers]]
    for = '/**'
    [server.headers.values]
      Content-Security-Policy = 'script-src localhost:1313'
      Referrer-Policy = 'strict-origin-when-cross-origin'
      X-Content-Type-Options = 'nosniff'
      X-Frame-Options = 'DENY'
      X-XSS-Protection = '1; mode=block'

{
   "server": {
      "headers": [
         {
            "for": "/**",
            "values": {
               "Content-Security-Policy": "script-src localhost:1313",
               "Referrer-Policy": "strict-origin-when-cross-origin",
               "X-Content-Type-Options": "nosniff",
               "X-Frame-Options": "DENY",
               "X-XSS-Protection": "1; mode=block"
            }
         }
      ]
   }
}

由于这仅适用于"开发阶段"，因此将其放在 development 环境之下可能是有意义的：

config/development/server.

headers:
- for: /**
  values:
    Content-Security-Policy: script-src localhost:1313
    Referrer-Policy: strict-origin-when-cross-origin
    X-Content-Type-Options: nosniff
    X-Frame-Options: DENY
    X-XSS-Protection: 1; mode=block

[[headers]]
  for = '/**'
  [headers.values]
    Content-Security-Policy = 'script-src localhost:1313'
    Referrer-Policy = 'strict-origin-when-cross-origin'
    X-Content-Type-Options = 'nosniff'
    X-Frame-Options = 'DENY'
    X-XSS-Protection = '1; mode=block'

{
   "headers": [
      {
         "for": "/**",
         "values": {
            "Content-Security-Policy": "script-src localhost:1313",
            "Referrer-Policy": "strict-origin-when-cross-origin",
            "X-Content-Type-Options": "nosniff",
            "X-Frame-Options": "DENY",
            "X-XSS-Protection": "1; mode=block"
         }
      }
   ]
}

您还可以为服务器指定简单的重定向规则。语法与 Netlify 的语法类似。

请注意，具有 200 的状态代码将触发 URL 重写，这是 SPA 场景中所需的，例如：

config/development/server.

redirects:
- force: false
  from: /myspa/**
  status: 200
  to: /myspa/

[[redirects]]
  force = false
  from = '/myspa/**'
  status = 200
  to = '/myspa/'

{
   "redirects": [
      {
         "force": false,
         "from": "/myspa/**",
         "status": 200,
         "to": "/myspa/"
      }
   ]
}

将 force=true 设置为将进行重定向，即使路径中存在现有内容。请注意，在 Hugo 0.76 之前，force 是默认行为，这与 Netlify 的行为一致。

404 服务器错误页面

默认情况下，当运行 hugo server 时，Hugo 会使用 404.html 模板来呈现所有 404 错误页面。但是，如果您已经为您的服务器配置添加了一个或多个重定向，则需要显式添加 404 重定向，例如：

config/development/server.

redirects:
- from: /**
  status: 404
  to: /404.html

[[redirects]]
  from = '/**'
  status = 404
  to = '/404.html'

{
   "redirects": [
      {
         "from": "/**",
         "status": 404,
         "to": "/404.html"
      }
   ]
}

配置标题大小写

默认情况下，Hugo 在创建自动章节标题和使用 strings.Title 函数转换字符串时遵循美联社风格指南中发布的大写规则。

通过在站点配置中设置 titleCaseStyle，可以更改此行为。可以设置为以下任何值：

ap: 使用美联社风格指南中发布的大写规则。
chicago: 使用芝加哥手册风格指南中发布的大写规则。
go: 每个字的首字母大写。
firstupper: 只有第一个字的首字母大写。
none: 禁用自动章节标题的转换，并禁用 strings.Title 函数执行的转换。如果希望根据需要手动大写章节标题，并绕过对 strings.Title 的强调主题用法，这将非常有用。

配置环境变量

HUGO_NUMWORKERMULTIPLIER: 可以设置为增加或减少在 Hugo 中的并行处理中使用的工作进程数。如果未设置，将使用逻辑 CPU 的数量。

配置查找顺序

与模板的 [查找顺序] 类似，Hugo 在默认情况下有一套规则来搜索站点根目录下的配置文件:

./hugo.toml
./hugo.yaml
./hugo.json

在配置文件中，您可以指定 Hugo 如何渲染您的网站，控制网站的菜单，并任意定义项目特定的全站参数。

示例配置

以下是一个典型的配置文件示例。在 params: 下嵌套的值将填充 [.Site.Params] 变量，以供 [模板] 中使用:

hugo.

baseURL: https://yoursite.example.com/
params:
  AuthorName: Jon Doe
  GitHubUser: spf13
  ListOfFoo:
  - foo1
  - foo2
  SidebarRecentLimit: 5
  Subtitle: Hugo is Absurdly Fast!
permalinks:
  posts: /:year/:month/:title/
title: My Hugo Site

baseURL = 'https://yoursite.example.com/'
title = 'My Hugo Site'
[params]
  AuthorName = 'Jon Doe'
  GitHubUser = 'spf13'
  ListOfFoo = ['foo1', 'foo2']
  SidebarRecentLimit = 5
  Subtitle = 'Hugo is Absurdly Fast!'
[permalinks]
  posts = '/:year/:month/:title/'

{
   "baseURL": "https://yoursite.example.com/",
   "params": {
      "AuthorName": "Jon Doe",
      "GitHubUser": "spf13",
      "ListOfFoo": [
         "foo1",
         "foo2"
      ],
      "SidebarRecentLimit": 5,
      "Subtitle": "Hugo is Absurdly Fast!"
   },
   "permalinks": {
      "posts": "/:year/:month/:title/"
   },
   "title": "My Hugo Site"
}

通过环境变量进行配置

除了前面提到的 3 个配置选项外，还可以通过操作系统环境变量来定义配置键值。

例如，下面的命令可以在类Unix系统中有效地设置网站的标题:

$ env HUGO_TITLE="Some Title" hugo

如果您使用像 Netlify 这样的服务来部署网站，这将非常有用。查看 Hugo 文档中的 Netlify 配置文件进行参考。

如果使用下划线分隔的变量名，上述命令将无效。Hugo 根据 HUGO 后的第一个字符来确定分隔符的使用情况。这使得您可以使用 HUGOxPARAMSxAPI_KEY=abcdefgh 形式的环境变量，使用任何允许的分隔符。

在呈现时忽略内容和数据文件

**注意：**这个方法能够起作用，但我们建议您使用更新且更强大的 includeFiles 和 excludeFiles 配置方法。

要在渲染站点时从 content、data 和 i18n 目录中排除特定文件，请将 ignoreFiles 设置为与绝对文件路径匹配的一个或多个正则表达式。

要忽略以 .foo 或 .boo 结尾的文件:

hugo.

ignoreFiles:
- \.foo$
- \.boo$

ignoreFiles = ['\.foo$', '\.boo$']

{
   "ignoreFiles": [
      "\\.foo$",
      "\\.boo$"
   ]
}

要通过绝对文件路径忽略一个文件：

hugo.

ignoreFiles:
- ^/home/user/project/content/test\.md$

ignoreFiles = ['^/home/user/project/content/test\.md$']

{
   "ignoreFiles": [
      "^/home/user/project/content/test\\.md$"
   ]
}

配置正文前的元数据

配置日期

日期在 Hugo 中非常重要，您可以通过在 hugo.toml 中添加 frontmatter 部分来配置 Hugo 如何为内容页面分配日期。

默认配置如下：

hugo.

frontmatter:
  date:
  - date
  - publishdate
  - pubdate
  - published
  - lastmod
  - modified
  expiryDate:
  - expirydate
  - unpublishdate
  lastmod:
  - :git
  - lastmod
  - modified
  - date
  - publishdate
  - pubdate
  - published
  publishDate:
  - publishdate
  - pubdate
  - published
  - date

[frontmatter]
  date = ['date', 'publishdate', 'pubdate', 'published', 'lastmod', 'modified']
  expiryDate = ['expirydate', 'unpublishdate']
  lastmod = [':git', 'lastmod', 'modified', 'date', 'publishdate', 'pubdate', 'published']
  publishDate = ['publishdate', 'pubdate', 'published', 'date']

{
   "frontmatter": {
      "date": [
         "date",
         "publishdate",
         "pubdate",
         "published",
         "lastmod",
         "modified"
      ],
      "expiryDate": [
         "expirydate",
         "unpublishdate"
      ],
      "lastmod": [
         ":git",
         "lastmod",
         "modified",
         "date",
         "publishdate",
         "pubdate",
         "published"
      ],
      "publishDate": [
         "publishdate",
         "pubdate",
         "published",
         "date"
      ]
   }
}

例如，如果您的一些内容中有非标准日期参数，您可以重写 date 设置：

hugo.

frontmatter:
  date:
  - myDate
  - :default

[frontmatter]
  date = ['myDate', ':default']

{
   "frontmatter": {
      "date": [
         "myDate",
         ":default"
      ]
   }
}

:default 是默认配置的快捷方式。以上述设置，.Date 的日期值将在 myDate 中如果存在，则 .Date 将设置为 myDate 的日期值；如果不存在，则会查找 date、publishDate、lastmod 并选择第一个有效的日期。

在右侧的列表中，以 “:” 开头的值是具有特殊意义的日期处理程序（参见下面）。其他的只是您的正文前字段配置中的日期参数名称（不区分大小写）。请注意，Hugo 还为上述日期参数提供了一些内置的别名，lastmod => modified，publishDate => pubdate，published 和 expiryDate => unpublishdate。例如，使用 pubDate 作为正文前的日期，将默认设置为分配给 .PublishDate。

特殊日期处理程序如下：

:fileModTime: 从内容文件的上次修改时间戳中获取日期。

下面是一个示例：

hugo.

frontmatter:
  lastmod:
  - lastmod
  - :fileModTime
  - :default

[frontmatter]
  lastmod = ['lastmod', ':fileModTime', ':default']

{
   "frontmatter": {
      "lastmod": [
         "lastmod",
         ":fileModTime",
         ":default"
      ]
   }
}

以上设置将首先使用正文前字段所在位置的 lastmod 来提取 .Lastmod 的值，然后使用内容文件的修改时间戳。最后，:default 在此处可能是不需要的，但 Hugo 最后将在 :git、date 和 publishDate 中查找有效日期。

:filename: 从内容文件的文件名中获取日期。例如，2018-02-22-mypage.md 将提取日期 2018-02-22。另外，如果未设置 slug，那么将使用 mypage 作为 .Slug 的值。

下面是一个示例：

hugo.

frontmatter:
  date:
  - :filename
  - :default

[frontmatter]
  date = [':filename', ':default']

{
   "frontmatter": {
      "date": [
         ":filename",
         ":default"
      ]
   }
}

以上设置将首先从文件名中提取 .Date 的值，然后查找正文前字段参数 date、publishDate 和最后一个是 lastmod。

:git: 这是与此内容文件的最后修改的 Git 作者日期。只有在设置了 --enableGitInfo 或在站点配置中设置了 enableGitInfo = true 时，才会设置该值。

配置更多输出格式

Hugo v0.20 引入了将内容渲染为多种输出格式（例如 JSON、AMP HTML 或 CSV）的功能。有关如何将这些值添加到您的 Hugo 项目的配置文件的信息，请参阅[输出格式]。

配置 minify

默认配置如下：

hugo.

minify:
  disableCSS: false
  disableHTML: false
  disableJS: false
  disableJSON: false
  disableSVG: false
  disableXML: false
  minifyOutput: false
  tdewolff:
    css:
      keepCSS2: true
      precision: 0
    html:
      keepComments: false
      keepConditionalComments: true
      keepDefaultAttrVals: true
      keepDocumentTags: true
      keepEndTags: true
      keepQuotes: false
      keepWhitespace: false
    js:
      keepVarNames: false
      precision: 0
      version: 2022
    json:
      keepNumbers: false
      precision: 0
    svg:
      keepComments: false
      precision: 0
    xml:
      keepWhitespace: false

[minify]
  disableCSS = false
  disableHTML = false
  disableJS = false
  disableJSON = false
  disableSVG = false
  disableXML = false
  minifyOutput = false
  [minify.tdewolff]
    [minify.tdewolff.css]
      keepCSS2 = true
      precision = 0
    [minify.tdewolff.html]
      keepComments = false
      keepConditionalComments = true
      keepDefaultAttrVals = true
      keepDocumentTags = true
      keepEndTags = true
      keepQuotes = false
      keepWhitespace = false
    [minify.tdewolff.js]
      keepVarNames = false
      precision = 0
      version = 2022
    [minify.tdewolff.json]
      keepNumbers = false
      precision = 0
    [minify.tdewolff.svg]
      keepComments = false
      precision = 0
    [minify.tdewolff.xml]
      keepWhitespace = false

{
   "minify": {
      "disableCSS": false,
      "disableHTML": false,
      "disableJS": false,
      "disableJSON": false,
      "disableSVG": false,
      "disableXML": false,
      "minifyOutput": false,
      "tdewolff": {
         "css": {
            "keepCSS2": true,
            "precision": 0
         },
         "html": {
            "keepComments": false,
            "keepConditionalComments": true,
            "keepDefaultAttrVals": true,
            "keepDocumentTags": true,
            "keepEndTags": true,
            "keepQuotes": false,
            "keepWhitespace": false
         },
         "js": {
            "keepVarNames": false,
            "precision": 0,
            "version": 2022
         },
         "json": {
            "keepNumbers": false,
            "precision": 0
         },
         "svg": {
            "keepComments": false,
            "precision": 0
         },
         "xml": {
            "keepWhitespace": false
         }
      }
   }
}

配置文件缓存

自 Hugo 0.52 起，您可以配置的不仅仅是 cacheDir。这是默认配置：

hugo.

caches:
  assets:
    dir: :resourceDir/_gen
    maxAge: -1
  getcsv:
    dir: :cacheDir/:project
    maxAge: -1
  getjson:
    dir: :cacheDir/:project
    maxAge: -1
  getresource:
    dir: :cacheDir/:project
    maxAge: -1
  images:
    dir: :resourceDir/_gen
    maxAge: -1
  modules:
    dir: :cacheDir/modules
    maxAge: -1

[caches]
  [caches.assets]
    dir = ':resourceDir/_gen'
    maxAge = -1
  [caches.getcsv]
    dir = ':cacheDir/:project'
    maxAge = -1
  [caches.getjson]
    dir = ':cacheDir/:project'
    maxAge = -1
  [caches.getresource]
    dir = ':cacheDir/:project'
    maxAge = -1
  [caches.images]
    dir = ':resourceDir/_gen'
    maxAge = -1
  [caches.modules]
    dir = ':cacheDir/modules'
    maxAge = -1

{
   "caches": {
      "assets": {
         "dir": ":resourceDir/_gen",
         "maxAge": -1
      },
      "getcsv": {
         "dir": ":cacheDir/:project",
         "maxAge": -1
      },
      "getjson": {
         "dir": ":cacheDir/:project",
         "maxAge": -1
      },
      "getresource": {
         "dir": ":cacheDir/:project",
         "maxAge": -1
      },
      "images": {
         "dir": ":resourceDir/_gen",
         "maxAge": -1
      },
      "modules": {
         "dir": ":cacheDir/modules",
         "maxAge": -1
      }
   }
}

您可以在自己的 hugo.toml 中重写这些缓存设置中的任何一个。

关键字说明

:cacheDir: 请参阅配置 cacheDir。
:project: 当前 Hugo 项目的基本目录名称。这意味着，按默认设置，每个项目将有单独的文件缓存，这意味着当您运行 hugo --gc 时，您不会触及在同一台计算机上运行的其他 Hugo 项目相关的文件。有关其他 CI 供应商的说明，请查看他们的文档。有关 CircleCI 的示例，请参阅此配置。

在 Go 的 os.UserCacheDir 定义的操作系统用户缓存目录下的 hugo_cache 目录。在 Unix 系统上，这是根据 basedir-spec-latest 的设置，如果非空，则为 $XDG_CACHE_HOME，否则为 $HOME/.cache。在 MacOS 上，这是 $HOME/Library/Caches。在 Windows 上，这是 %LocalAppData%。在 Plan 9 上，这是 $home/lib/cache。
在操作系统临时目录下的 hugo_cache_$USER 目录。

如果要知道当前的 cacheDir 的值，可以运行 hugo config，例如：hugo config | grep cachedir。

配置文件

hugo.toml 与 config.toml

配置目录

从主题合并配置

所有配置设置

archetypeDir

assetDir

baseURL

build

buildDrafts (false)

buildExpired

buildFuture

caches

cascade

canonifyURLs

cleanDestinationDir

contentDir

copyright

dataDir

defaultContentLanguage

defaultContentLanguageInSubdir

disableAliases

disableHugoGeneratorInject

disableKinds

disableLiveReload

disablePathToLower

enableEmoji

enableGitInfo

enableInlineShortcodes

enableMissingTranslationPlaceholders

enableRobotsTXT

frontmatter

hasCJKLanguage

imaging

languageCode

languages

disableLanguages

markup

mediaTypes

menus

minify

module

newContentEditor

noChmod

noTimes

outputFormats

paginate

paginatePath

permalinks

pluralizeListTitles

publishDir

related

relativeURLs

refLinksErrorLevel

refLinksNotFoundURL

removePathAccents

rssLimit

sectionPagesMenu

security

sitemap

summaryLength

taxonomies

theme

themesDir

timeout

timeZone

title

titleCaseStyle

uglyURLs

watch

配置构建

配置缓存集装箱

配置服务器

404 服务器错误页面

配置标题大小写

配置环境变量

配置查找顺序

示例配置

通过环境变量进行配置

在呈现时忽略内容和数据文件