配置 Hugo

配置文件

在项目根目录下创建一个站点配置文件，命名为 hugo.toml 、 hugo.yaml 或 hugo.json ，优先级按此顺序排列。

my-project/
└── hugo.toml

一个简单的示例：

hugo.

baseURL: https://example.org/
languageCode: en-us
params:
  contact:
    email: [email protected]
    phone: +1 202-555-1212
  subtitle: The Best Widgets on Earth
title: ABC Widgets, Inc.

baseURL = 'https://example.org/'
languageCode = 'en-us'
title = 'ABC Widgets, Inc.'
[params]
  subtitle = 'The Best Widgets on Earth'
  [params.contact]
    email = '[email protected]'
    phone = '+1 202-555-1212'

{
   "baseURL": "https://example.org/",
   "languageCode": "en-us",
   "params": {
      "contact": {
         "email": "[email protected]",
         "phone": "+1 202-555-1212"
      },
      "subtitle": "The Best Widgets on Earth"
   },
   "title": "ABC Widgets, Inc."
}

要构建站点时使用不同的配置文件，请使用 --config 标志：

hugo --config other.toml

组合两个或多个配置文件，优先级从左到右：

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

配置目录

您可以通过环境、根配置键和语言来拆分配置，而不是使用单个站点配置文件。例如：

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

根配置键为 build 、 caches 、 cascade 、 deployment 、 frontmatter 、 imaging 、 languages 、 markup 、 mediatypes 、 menus 、 minify 、 module 、 outputformats 、 outputs 、 params 、 permalinks 、 privacy 、 related 、 security 、 segments 、 server 、 services 、 sitemap 和 taxonomies 。

省略根键

按根键拆分配置时，请省略给定文件中的根键。例如，这些是等效的：

hugo.

params:
  foo: bar

[params]
  foo = 'bar'

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

params.

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 ：

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 在运行 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。

合并主题的配置

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

none: 不合并。
shallow: 只为新的键添加值。
deep: 为新的键添加值，合并现有的值。

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

hugo.

build:
  _merge: none
caches:
  _merge: none
cascade:
  _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
security:
  _merge: none
segments:
  _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'
[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'
[security]
  _merge = 'none'
[segments]
  _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"
   },
   "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"
   },
   "security": {
      "_merge": "none"
   },
   "segments": {
      "_merge": "none"
   },
   "server": {
      "_merge": "none"
   },
   "services": {
      "_merge": "none"
   },
   "sitemap": {
      "_merge": "none"
   },
   "taxonomies": {
      "_merge": "none"
   }
}

所有配置设置

archetypeDir

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

assetDir

(string) Hugo 查找在 Hugo Pipes 中使用的资产文件的目录。默认为 assets 。Also see Module Mounts Config for an alternative way to configure this directory.

baseURL

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

build

请参阅配置构建。

buildDrafts

(bool) 构建时包含草稿。默认为 false 。

buildExpired

(bool) 包含已过期的内容。默认为 false 。

buildFuture

(bool) 包含具有未来发布日期的内容。默认为 false 。

caches

请参阅配置文件缓存。

canonifyURLs

(bool) 在启用此功能之前，请参阅详情。默认为 false 。

capitalizeListTitles

New in v0.123.3

(bool) 是否将自动列表标题大写。适用于章节、分类和术语页面。默认为 true 。您可以将站点配置中的大写风格更改为 ap 、 chicago 、 go 、 firstupper 或 none 之一。请参阅详情。

cascade

将默认配置值（前题）传递到内容树中的页面。站点配置中的选项与页面前题中的选项相同，请参阅前题级联。

cleanDestinationDir

(bool) 构建时，删除目标目录中在静态目录中找不到的文件。默认为 false 。

contentDir

(string) Hugo 从中读取内容文件的目录。默认为 content 。Also see Module Mounts Config for an alternative way to configure this directory.

copyright

dataDir

(string) Hugo 从中读取数据文件的目录。默认为 data 。Also see Module Mounts Config for an alternative way to configure this directory.

defaultContentLanguage

(string) 没有语言指示符的内容将默认为此语言。默认为 en 。

defaultContentLanguageInSubdir

(bool) 在子目录中呈现默认内容语言，例如 content/en/ 。然后，站点根目录 / 将重定向到 /en/ 。默认为 false 。

disableAliases

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

disableDefaultLanguageRedirect

New in v0.140.0

(bool) 当 DefaultContentLanguageInSubdir 为 true 时，禁用生成到默认语言的重定向。默认为 false 。

disableHugoGeneratorInject

(bool) 默认情况下，Hugo 仅在主页的 HTML 头部注入生成器元标记。您可以将其关闭，但我们真的希望您不要这样做，因为这是一种很好的方式来观察 Hugo 的流行程度。默认为 false 。

disableKinds

(string slice) 禁用指定页面种类的渲染，任何 404 、 home 、 page 、 robotstxt 、 rss 、 section 、 sitemap 、 taxonomy 或 term 。

disableLanguages

请参阅禁用语言。

disableLiveReload

(bool) 禁用浏览器窗口的自动实时重新加载。默认为 false 。

disablePathToLower

(bool) 不要将 url/path 转换为小写。默认为 false 。

enableEmoji

(bool) 为页面内容启用 Emoji 表情符号支持；请参阅 emoji 短代码快速参考指南。默认为 false 。

enableGitInfo

(bool) 为每个页面启用 .GitInfo 对象（如果 Hugo 站点由 Git 版本控制）。然后，这将使用该内容文件的最后一次 git 提交日期更新每个页面的 Lastmod 参数。默认为 false 。

enableMissingTranslationPlaceholders

(bool) 如果缺少翻译，则显示占位符而不是默认值或空字符串。默认为 false 。

enableRobotsTXT

(bool) 启用 robots.txt 文件的生成。默认为 false 。

environment

(string) 构建环境。运行 hugo 时默认为 production ，运行 hugo server 时默认为 development 。请参阅配置目录。

frontmatter

请参阅前题配置。

hasCJKLanguage

(bool) 如果为真，则自动检测内容中的中文/日文/韩文语言。这将使 .Summary 和 .WordCount 对 CJK 语言的行为正确。默认为 false 。

ignoreCache

(bool) 忽略缓存目录。默认为 false 。

ignoreLogs

(string slice) 对应于您希望禁止的警告和错误的消息标识符切片。请参阅 erroridf 和 warnidf 。

ignoreVendorPaths

(string) 忽略 _vendor 目录中与给定 Glob 模式匹配的已引入模块。

imaging

请参阅图像处理配置。

languageCode

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

嵌入式 RSS 模板中的 <language> 元素
嵌入式别名模板中的 <html> 元素的 lang 属性
嵌入式开放图谱模板中的 og:locale meta 元素

如果存在一个或多个语言键，则在配置的根目录中存在时，此值将被忽略。请为每个语言键分别指定此值。

languages

请参阅配置语言。

layoutDir

(string) 包含模板的目录。默认为 layouts 。

markup

请参阅配置标记。

mediaTypes

请参阅配置媒体类型。

menus

请参阅菜单。

minify

请参阅配置压缩。

module

模块配置，请参阅模块配置。

newContentEditor

(string) 创建新内容时使用的编辑器。

noBuildLock

(bool) 不创建 .hugo_build.lock 文件。默认为 false 。

noChmod

(bool) 不同步文件的权限模式。默认为 false 。

noTimes

(bool) 不同步文件的修改时间。默认为 false 。

panicOnWarning

(bool) 是否在第一个 WARNING 时发生恐慌。默认为 false 。

permalinks

请参阅内容管理。

pluralizeListTitles

(bool) 是否将自动列表标题复数化。适用于章节页面。默认为 true 。

printI18nWarnings

(bool) 是否为每个缺失的翻译记录 WARNING。默认为 false 。

printPathWarnings

(bool) 当 Hugo 将两个或多个文件发布到同一路径时，是否记录 WARNING。默认为 false 。

printUnusedTemplates

(bool) 是否为每个未使用的模板记录 WARNING。默认为 false 。

publishDir

(string) Hugo 将写入最终静态站点（HTML 文件等）的目录。默认为 public 。

refLinksErrorLevel

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

refLinksNotFoundURL

(string) 在 ref 或 relref 中找不到页面引用时用作占位符的 URL。按原样使用。

请参阅相关内容。

relativeURLs

(bool) 在启用此功能之前，请参阅详情。默认为 false 。

removePathAccents

(bool) 从内容路径中的组合字符中删除非间隔标记。默认为 false 。

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

renderSegments

New in v0.124.0

(string slice) 要渲染的段列表。如果未设置，则将渲染所有内容。这更常在 CLI 标志中设置，例如 hugo --renderSegments segment1,segment2 。段名称必须与段配置中的名称匹配。

sectionPagesMenu

请参阅菜单。

security

请参阅安全策略。

segments

请参阅段。

sitemap

默认站点地图配置。

summaryLength

(int) 适用于自动摘要，在 Page 对象上调用 Summary 方法时要渲染的最小字数。在这种情况下， Summary 方法返回的内容将截断到最接近 summaryLength 的段落。

taxonomies

请参阅配置分类。

templateMetrics

(bool) 是否将模板执行指标打印到控制台。默认为 false 。请参阅模板指标。

templateMetricsHints

(bool) 是否将模板执行改进提示打印到控制台。当 templateMetrics 为 true 时适用。默认为 false 。请参阅模板指标。

theme

请参阅模块配置，了解如何导入主题。

themesDir

(string) Hugo 从中读取主题的目录。默认为 themes 。

timeout

(string) 生成页面内容的超时时间，指定为持续时间或秒数。注意： 这是用于终止递归内容生成的。如果您的页面生成速度很慢（例如，因为它们需要大量的图像处理或依赖于远程内容），您可能需要提高此限制。默认为 30s 。

timeZone

(string) 用于解析没有时区偏移的日期的时区，包括前题日期字段和传递给 time.AsTime 和 time.Format 模板函数的值。有效值的列表可能取决于系统，但应包括 UTC 、 Local 和 IANA 时区数据库中的任何位置。例如， America/Los_Angeles 和 Europe/Oslo 是有效的时区。

title

(string) 站点标题。

titleCaseStyle

(string) 默认为 ap 。请参阅配置标题大小写。

uglyURLs

(bool 或 map) 是否生成丑陋的 URL。默认为 false 。请参阅详情。

watch

(bool) 监视文件系统中的更改并根据需要重新创建。默认为 false 。

如果您在 *nix 机器上开发您的站点，这里有一个从命令行查找配置选项的便捷快捷方式：

cd ~/sites/yourhugosite
hugo config | grep emoji

显示的输出类似于

enableemoji: true

配置页面

New in v0.133.0

Page 对象上的这些方法在页面集合中导航到相对于当前页面的下一个或上一个页面：

Hugo 通过根据以下排序层次结构对页面集合进行排序来确定 下一个 和 上一个 页面：

字段	优先级	排序方向
`weight`	1	降序
`date`	2	降序
`linkTitle`	3	降序
`path`	4	降序

上表中的排序方向对应于这些默认站点配置值：

hugo.

page:
  nextPrevInSectionSortOrder: desc
  nextPrevSortOrder: desc

[page]
  nextPrevInSectionSortOrder = 'desc'
  nextPrevSortOrder = 'desc'

{
   "page": {
      "nextPrevInSectionSortOrder": "desc",
      "nextPrevSortOrder": "desc"
   }
}

要按升序排序所有字段：

hugo.

page:
  nextPrevInSectionSortOrder: asc
  nextPrevSortOrder: asc

[page]
  nextPrevInSectionSortOrder = 'asc'
  nextPrevSortOrder = 'asc'

{
   "page": {
      "nextPrevInSectionSortOrder": "asc",
      "nextPrevSortOrder": "asc"
   }
}

配置构建

请参阅配置构建。

配置服务器

这仅在运行 hugo server 时才相关，它允许在开发期间设置 HTTP 标头，这使您可以测试您的内容安全策略和类似内容。配置格式与 Netlify 的格式匹配，但具有更强大的 Glob 匹配：

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 的语法。

请注意， status 代码 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 在使用 404.html 模板运行 hugo server 时将渲染所有 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"
      }
   ]
}

对于多语言站点，请最后定义默认内容语言的重定向：

config/development/server.

defaultContentLanguage: en
defaultContentLanguageInSubdir: false
redirects:
- from: /fr/**
  status: 404
  to: /fr/404.html
- from: /**
  status: 404
  to: /404.html

defaultContentLanguage = 'en'
defaultContentLanguageInSubdir = false
[[redirects]]
  from = '/fr/**'
  status = 404
  to = '/fr/404.html'
[[redirects]]
  from = '/**'
  status = 404
  to = '/404.html'

{
   "defaultContentLanguage": "en",
   "defaultContentLanguageInSubdir": false,
   "redirects": [
      {
         "from": "/fr/**",
         "status": 404,
         "to": "/fr/404.html"
      },
      {
         "from": "/**",
         "status": 404,
         "to": "/404.html"
      }
   ]
}

如果您从子目录提供默认内容语言：

config/development/server.

defaultContentLanguage: en
defaultContentLanguageInSubdir: true
redirects:
- from: /fr/**
  status: 404
  to: /fr/404.html
- from: /**
  status: 404
  to: /en/404.html

defaultContentLanguage = 'en'
defaultContentLanguageInSubdir = true
[[redirects]]
  from = '/fr/**'
  status = 404
  to = '/fr/404.html'
[[redirects]]
  from = '/**'
  status = 404
  to = '/en/404.html'

{
   "defaultContentLanguage": "en",
   "defaultContentLanguageInSubdir": true,
   "redirects": [
      {
         "from": "/fr/**",
         "status": 404,
         "to": "/fr/404.html"
      },
      {
         "from": "/**",
         "status": 404,
         "to": "/en/404.html"
      }
   ]
}

配置标题大小写

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

通过将站点配置中的 titleCaseStyle 设置为以下任何值来更改此行为：

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

配置环境变量

DART_SASS_BINARY: (string) Dart Sass 可执行文件的绝对路径。默认情况下，Hugo 会在 PATH 环境变量中的每个路径中搜索可执行文件。
HUGO_ENVIRONMENT: (string) 覆盖默认环境，通常是 development 、 staging 或 production 之一。

HUGO_FILE_LOG_FORMAT: (string) 用于文件路径、行号和列号的格式字符串，在报告错误时显示，或者在从简码或 Markdown 渲染钩子调用 Position 方法时显示。有效标记为 :file 、 :line 和 :col 。默认为 :file::line::col 。

New in v0.123.0

HUGO_MEMORYLIMIT: (int) Hugo 在渲染您的站点时可以使用的最大系统内存量（以千兆字节为单位）。默认为系统总内存的 25%。
HUGO_NUMWORKERMULTIPLIER: (int) 并行处理中使用的 worker 数量。默认为逻辑 CPU 数量。

使用环境变量配置

可以通过操作系统环境变量定义配置键值对。

例如，以下命令将有效地设置类 Unix 系统上网站的标题：

$ env HUGO_TITLE="Some Title" hugo

如果您使用 Netlify 等服务来部署您的站点，这将非常有用。请查看 Hugo 文档中的 Netlify 配置文件了解示例。

如果您使用 snake_cased 变量名，则上述方法将不起作用。Hugo 通过 HUGO 之后第一个字符来确定要使用的分隔符。这允许您定义表单为 HUGOxPARAMSxAPI_KEY=abcdefgh 的环境变量，使用任何允许的分隔符。

渲染时忽略内容和数据文件

要渲染站点时从 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 如何为您的内容页面分配日期。您可以通过向 hugo.toml 添加 frontmatter 部分来实现此目的。

默认配置为：

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 、 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 时，才会设置此值。

配置压缩

有关详细信息，请参阅 tdewolff/minify 项目页面。

默认配置：

hugo.

minify:
  disableCSS: false
  disableHTML: false
  disableJS: false
  disableJSON: false
  disableSVG: false
  disableXML: false
  minifyOutput: false
  tdewolff:
    css:
      inline: false
      keepCSS2: true
      precision: 0
    html:
      keepComments: false
      keepConditionalComments: false
      keepDefaultAttrVals: true
      keepDocumentTags: true
      keepEndTags: true
      keepQuotes: false
      keepSpecialComments: true
      keepWhitespace: false
      templateDelims:
      - ""
      - ""
    js:
      keepVarNames: false
      precision: 0
      version: 2022
    json:
      keepNumbers: false
      precision: 0
    svg:
      inline: false
      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]
      inline = false
      keepCSS2 = true
      precision = 0
    [minify.tdewolff.html]
      keepComments = false
      keepConditionalComments = false
      keepDefaultAttrVals = true
      keepDocumentTags = true
      keepEndTags = true
      keepQuotes = false
      keepSpecialComments = true
      keepWhitespace = false
      templateDelims = ['', '']
    [minify.tdewolff.js]
      keepVarNames = false
      precision = 0
      version = 2022
    [minify.tdewolff.json]
      keepNumbers = false
      precision = 0
    [minify.tdewolff.svg]
      inline = false
      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": {
            "inline": false,
            "keepCSS2": true,
            "precision": 0
         },
         "html": {
            "keepComments": false,
            "keepConditionalComments": false,
            "keepDefaultAttrVals": true,
            "keepDocumentTags": true,
            "keepEndTags": true,
            "keepQuotes": false,
            "keepSpecialComments": true,
            "keepWhitespace": false,
            "templateDelims": [
               "",
               ""
            ]
         },
         "js": {
            "keepVarNames": false,
            "precision": 0,
            "version": 2022
         },
         "json": {
            "keepNumbers": false,
            "precision": 0
         },
         "svg": {
            "inline": false,
            "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
  misc:
    dir: :cacheDir/:project
    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.misc]
    dir = ':cacheDir/:project'
    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
      },
      "misc": {
         "dir": ":cacheDir/:project",
         "maxAge": -1
      },
      "modules": {
         "dir": ":cacheDir/modules",
         "maxAge": -1
      }
   }
}

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

解释关键字

cacheDir: (string) 请参阅配置 cacheDir 。
project: (string) 当前 Hugo 项目的基目录名称。这意味着，在其默认设置中，每个项目都将拥有独立的文件缓存，这意味着当您执行 hugo --gc 时，您不会接触到在同一台 PC 上运行的其他 Hugo 项目的相关文件。
resourceDir: (string) 这是 resourceDir 配置选项的值。
maxAge: (string) 这是缓存条目被逐出之前的持续时间，-1 表示永远，0 有效地关闭了该特定缓存。使用 Go 的 time.Duration ，因此有效值为 "10s" （10 秒）、 "10m" （10 分钟）和 "10h" （10 小时）。
dir: (string) 此缓存的文件将存储到的绝对路径。允许的起始占位符为 :cacheDir 和 :resourceDir （见上文）。

配置 cacheDir

这是 Hugo 默认存储其文件缓存的目录。请参阅配置文件缓存。

这可以通过 cacheDir 配置选项或通过 OS 环境变量 HUGO_CACHEDIR 来设置。

如果没有设置此项，Hugo 将按优先级顺序使用：

如果在 Netlify 上运行： /opt/build/cache/hugo_cache/ 。这意味着如果您在 Netlify 上运行构建，则所有使用 :cacheDir 配置的缓存都将在下一次构建中保存和恢复。对于其他 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 。 New in v0.116.0
在操作系统临时目录下的 hugo_cache_$USER 目录中。

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

配置 HTTP 缓存

New in v0.127.0

请注意，此配置当前仅与使用 resources.GetRemote 函数时相关。

Hugo 中的缓存是分层的：

Dynacache: 一个内存中的 LRU 缓存，会在更改时、缓存破坏器匹配以及内存不足的情况下被逐出。
HTTP 缓存: 为远程资源启用 HTTP 缓存行为 (RFC 9111)。这最适合具有正确设置的 HTTP 缓存头的资源。HTTP 缓存使用文件缓存来存储和提供缓存的资源。
文件缓存: 请参阅文件缓存。

默认 HTTP 缓存禁用所有内容：

hugo.

HTTPCache:
  cache:
    for:
      excludes:
      - '**'
      includes: null
  polls:
  - disable: true
    for:
      excludes: null
      includes:
      - '**'
    high: 0s
    low: 0s

[HTTPCache]
  [HTTPCache.cache]
    [HTTPCache.cache.for]
      excludes = ['**']
  [[HTTPCache.polls]]
    disable = true
    high = '0s'
    low = '0s'
    [HTTPCache.polls.for]
      includes = ['**']

{
   "HTTPCache": {
      "cache": {
         "for": {
            "excludes": [
               "**"
            ],
            "includes": null
         }
      },
      "polls": [
         {
            "disable": true,
            "for": {
               "excludes": null,
               "includes": [
                  "**"
               ]
            },
            "high": "0s",
            "low": "0s"
         }
      ]
   }
}

caching: 为一组已配置的资源启用 RFC 9111 缓存行为。即使未达到其配置的 TTL，陈旧的资源也将从文件缓存中刷新。
polling: 为一组资源启用轮询。请注意，即使禁用了 HTTP 缓存，您也可以为资源启用轮询。此设置仅在监视模式下（例如 hugo server ）使用。当检测到资源更改时，该更改将触发使用该资源的页面的重新构建。

配置段

New in v0.124.0

每个段包含零个或多个 exclude 过滤器和零个或多个 include 过滤器。
每个过滤器包含一个或多个字段 Glob 匹配器。
一个部分中的每个过滤器（ exclude 或 include ）进行 OR 运算，一个过滤器中的每个匹配器进行 AND 运算。

过滤器中可使用的字段有：

path: 逻辑页面路径。
lang: 页面语言。
kind: 页面的种类。
output: 页面的输出格式。

建议将粗粒度过滤器（例如，用于语言和输出格式）放在 excludes 部分中，例如：

hugo.

segments:
  segment1:
    excludes:
    - lang: n*
    - lang: en
      output: rss
    includes:
    - kind: '{home,term,taxonomy}'
    - path: '{/docs,/docs/**}'

[segments]
  [segments.segment1]
    [[segments.segment1.excludes]]
      lang = 'n*'
    [[segments.segment1.excludes]]
      lang = 'en'
      output = 'rss'
    [[segments.segment1.includes]]
      kind = '{home,term,taxonomy}'
    [[segments.segment1.includes]]
      path = '{/docs,/docs/**}'

{
   "segments": {
      "segment1": {
         "excludes": [
            {
               "lang": "n*"
            },
            {
               "lang": "en",
               "output": "rss"
            }
         ],
         "includes": [
            {
               "kind": "{home,term,taxonomy}"
            },
            {
               "path": "{/docs,/docs/**}"
            }
         ]
      }
   }
}

通过上述配置，您可以通过配置 renderSegments 或设置 --renderSegments 标志来仅渲染 segment1 中的页面：

hugo --renderSegments segment1

可以配置多个段， --renderSegments 标志可以采用以逗号分隔的段列表。

此功能的一些用例：

拆分大型站点的构建。
通过仅渲染站点的子集来加快开发过程中的构建速度。
部分重建，例如每小时渲染主页和“新闻部分”，每周渲染整个站点一次。
仅渲染例如 JSON 输出格式以推送到例如搜索索引。

配置文件

配置目录

省略根键

递归解析

示例

合并主题的配置

所有配置设置

archetypeDir

assetDir

baseURL

build

buildDrafts

buildExpired

buildFuture

caches

canonifyURLs

capitalizeListTitles

cascade

cleanDestinationDir

contentDir

copyright

dataDir

defaultContentLanguage

defaultContentLanguageInSubdir

disableAliases

disableDefaultLanguageRedirect

disableHugoGeneratorInject

disableKinds

disableLanguages

disableLiveReload

disablePathToLower

enableEmoji

enableGitInfo

enableMissingTranslationPlaceholders

enableRobotsTXT

environment

frontmatter

hasCJKLanguage

ignoreCache

ignoreLogs

ignoreVendorPaths

imaging

languageCode

languages

layoutDir

markup

mediaTypes

menus

minify

module

newContentEditor

noBuildLock

noChmod

noTimes

outputFormats

page

pagination

panicOnWarning

permalinks

pluralizeListTitles

printI18nWarnings

printPathWarnings

printUnusedTemplates

publishDir

refLinksErrorLevel

refLinksNotFoundURL

related

relativeURLs

removePathAccents

renderSegments

sectionPagesMenu

security

segments

sitemap

summaryLength

taxonomies

templateMetrics

templateMetricsHints

theme

themesDir