# 配置
> Hugo 配置的组织方式、配置文件与配置目录、按环境覆盖、合并策略与环境变量。
- 本页规范地址：https://hugozh.cn/configuration/
- 最近更新：2026-10-02
- 站点：Hugo 中文文档（https://hugozh.cn/）· 社区维护的非官方中文翻译

## 本章页面
- [配置简介](https://hugozh.cn/configuration/introduction/)：介绍配置文件、配置目录、环境变量与合并策略。（Markdown：https://hugozh.cn/configuration/introduction/index.md）
- [全部设置](https://hugozh.cn/configuration/all/)：按键名索引 Hugo 全部顶层配置项，含类型、默认值与分区说明。（Markdown：https://hugozh.cn/configuration/all/index.md）
- [构建配置](https://hugozh.cn/configuration/build/)：配置构建统计、缓存失效与目标目录清理等全局构建选项。（Markdown：https://hugozh.cn/configuration/build/index.md）
- [缓存配置](https://hugozh.cn/configuration/caches/)：配置文件缓存的用途、键、路径标记与垃圾回收。（Markdown：https://hugozh.cn/configuration/caches/index.md）
- [级联配置](https://hugozh.cn/configuration/cascade/)：用 cascade 把页面参数、目标与切片级联到多组页面。（Markdown：https://hugozh.cn/configuration/cascade/index.md）
- [内容类型配置](https://hugozh.cn/configuration/content-types/)：通过 contentTypes 控制哪些媒体类型作为可发布资源。（Markdown：https://hugozh.cn/configuration/content-types/index.md）
- [部署目标配置](https://hugozh.cn/configuration/deployment/)：配置 hugo deploy 的目标、匹配器与上传顺序。（Markdown：https://hugozh.cn/configuration/deployment/index.md）
- [前置元数据配置](https://hugozh.cn/configuration/front-matter/)：配置日期回退顺序、字段别名与可用记号。（Markdown：https://hugozh.cn/configuration/front-matter/index.md）
- [HTTP 缓存配置](https://hugozh.cn/configuration/http-cache/)：配置远程资源的 HTTP 缓存与轮询策略。（Markdown：https://hugozh.cn/configuration/http-cache/index.md）
- [图像处理配置](https://hugozh.cn/configuration/imaging/)：配置图像处理的对齐锚点、重采样与各格式编码参数。（Markdown：https://hugozh.cn/configuration/imaging/index.md）
- [语言配置](https://hugozh.cn/configuration/languages/)：配置多语言项目的基础设置、各语言设置与多主机部署。（Markdown：https://hugozh.cn/configuration/languages/index.md）
- [Markup 配置](https://hugozh.cn/configuration/markup/)：配置 Markdown 渲染器、代码高亮与目录生成参数。（Markdown：https://hugozh.cn/configuration/markup/index.md）
- [媒体类型配置](https://hugozh.cn/configuration/media-types/)：定义媒体类型及其后缀，供输出格式引用。（Markdown：https://hugozh.cn/configuration/media-types/index.md）
- [菜单配置](https://hugozh.cn/configuration/menus/)：在项目配置中集中定义各菜单的菜单项。（Markdown：https://hugozh.cn/configuration/menus/index.md）
- [压缩配置](https://hugozh.cn/configuration/minify/)：通过 minify 配置精简站点输出的各类资源。（Markdown：https://hugozh.cn/configuration/minify/index.md）
- [模块配置](https://hugozh.cn/configuration/module/)：配置 Hugo 模块的导入、挂载与版本要求。（Markdown：https://hugozh.cn/configuration/module/index.md）
- [输出格式配置](https://hugozh.cn/configuration/output-formats/)：定义和调整输出格式，控制页面的渲染产物。（Markdown：https://hugozh.cn/configuration/output-formats/index.md）
- [输出配置](https://hugozh.cn/configuration/outputs/)：按页面类型配置站点要渲染的输出格式。（Markdown：https://hugozh.cn/configuration/outputs/index.md）
- [页面配置](https://hugozh.cn/configuration/page/)：配置 Page 对象上「下一篇」「上一篇」的排序方向。（Markdown：https://hugozh.cn/configuration/page/index.md）
- [参数配置](https://hugozh.cn/configuration/params/)：用 params 区段定义自定义站点参数，并在模板中读取。（Markdown：https://hugozh.cn/configuration/params/index.md）
- [分页配置](https://hugozh.cn/configuration/pagination/)：配置每页条目数、翻页 URL 片段与别名生成行为。（Markdown：https://hugozh.cn/configuration/pagination/index.md）
- [永久链接配置](https://hugozh.cn/configuration/permalinks/)：用 pattern 与目标匹配器自定义页面 URL 的生成规则。（Markdown：https://hugozh.cn/configuration/permalinks/index.md）
- [隐私配置](https://hugozh.cn/configuration/privacy/)：配置内嵌模板以帮助满足各地区的隐私法规。（Markdown：https://hugozh.cn/configuration/privacy/index.md）
- [相关内容配置](https://hugozh.cn/configuration/related-content/)：通过索引与阈值控制相关内容的匹配方式。（Markdown：https://hugozh.cn/configuration/related-content/index.md）
- [角色配置](https://hugozh.cn/configuration/roles/)：定义角色及其权重，控制多角色站点的构建顺序。（Markdown：https://hugozh.cn/configuration/roles/index.md）
- [安全配置](https://hugozh.cn/configuration/security/)：用允许列表限制外部命令、远程通信与 Node.js 权限。（Markdown：https://hugozh.cn/configuration/security/index.md）
- [片段配置](https://hugozh.cn/configuration/segments/)：通过 segments 配置按片段渲染站点，加快构建速度。（Markdown：https://hugozh.cn/configuration/segments/index.md）
- [服务器配置](https://hugozh.cn/configuration/server/)：配置 Hugo 开发服务器的请求头与重定向规则。（Markdown：https://hugozh.cn/configuration/server/index.md）
- [服务配置](https://hugozh.cn/configuration/services/)：通过 services 配置 Hugo 内嵌模板所需的凭据与行为。（Markdown：https://hugozh.cn/configuration/services/index.md）
- [站点地图配置](https://hugozh.cn/configuration/sitemap/)：通过 sitemap 配置站点地图的字段、文件名与开关。（Markdown：https://hugozh.cn/configuration/sitemap/index.md）
- [分类法配置](https://hugozh.cn/configuration/taxonomies/)：通过 taxonomies 配置定义分类法及其单复数映射关系。（Markdown：https://hugozh.cn/configuration/taxonomies/index.md）
- [丑陋 URL 配置](https://hugozh.cn/configuration/ugly-urls/)：让页面输出为带文件扩展名的丑陋 URL。（Markdown：https://hugozh.cn/configuration/ugly-urls/index.md）
- [版本配置](https://hugozh.cn/configuration/versions/)：定义内容版本、默认版本与版本权重排序。（Markdown：https://hugozh.cn/configuration/versions/index.md）

---
## 通用设置与配置分类

项目配置中的每个顶层键，要么是通用设置（general setting），要么是配置分类（configuration category）。

通用设置是单个值，例如 `baseURL` 或 `title`；配置分类把相关的嵌套设置归为一组，例如 `markup`、`menus` 或 `params`。

```toml
baseURL = 'https://example.org/'
title = 'My New Hugo Site'

[params]
subtitle = 'The Best Widgets on Earth'
```

上例中，`baseURL` 与 `title` 是通用设置，`params` 是配置分类。

## 合理的默认值

Hugo 的配置项很多，但默认值通常已经够用。新项目只需要这几个设置：

```toml
baseURL = 'https://example.org/'
locale = 'en-us'
title = 'My New Hugo Site'
```

只定义与默认值不同的设置。配置文件越小，越容易阅读、理解与排查问题。

> 最好的配置文件就是短配置文件。

## 配置文件

在项目根目录创建项目配置文件，命名为 `hugo.toml`、`hugo.yaml` 或 `hugo.json`，优先级也按此顺序。

```text
my-project/
└── hugo.toml
```

一个简单的例子：

```toml
baseURL = 'https://example.org/'
locale = 'en-us'
title = 'ABC Widgets, Inc.'

[params]
subtitle = 'The Best Widgets on Earth'

[params.contact]
email = 'info@example.org'
phone = '+1 202-555-1212'
```

构建时想改用别的配置文件，可以使用 `--config` 参数：

```bash
hugo build --config other.toml
```

也可以合并两个或多个配置文件，优先级从左到右：

```bash
hugo build --config a.toml,b.yaml,c.json
```

Hugo 按列出的顺序加载文件，后一个文件会递归覆盖前一个文件中同名的键；也就是说，键冲突时以最后列出的文件为准。

## 配置目录

除单个配置文件外，还可以按环境（environment）、配置分类与语言把配置拆分到 `config` 目录。Hugo 先加载 `_default` 目录，再加载当前环境对应的目录，因此键冲突时环境专属的值生效。例如：

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

配置分类指 `markup`、`menus`、`params`、`module`、`services`、`taxonomies` 这类分组，完整列表见官方文档的 All settings 页面。

### 省略或包含分类名

自 v0.162.0 起，按配置分类拆分时，组件文件中可以省略、也可以保留分类名。例如下面两种写法等价：

```toml
# config/_default/hugo.toml
[params]
foo = 'bar'
```

```toml
# config/_default/params.toml
foo = 'bar'
```

对 `menus` 这类「值为映射到切片」的键同样适用，`[[main]]` 与 `[[menus.main]]` 等价。而对 `cascade`、`permalinks` 这类纯切片类型的键，则必须写出分类名。

> 只有当分类名是文件中的唯一键，且与文件的基本名一致时，Hugo 才会把这一层「解包」。

### 递归解析

Hugo 会递归解析 `config` 目录，因此可以把配置文件放进子目录，例如 `config/_default/navigation/menus.en.toml`。

### 示例

```text
my-project/
└── config/
    ├── _default/
    │   └── hugo.toml
    ├── production/
    │   └── hugo.toml
    └── staging/
        └── hugo.toml
```

以 Google Analytics 为例，它要求在项目配置中填写 Google 标记 ID：

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

现在有两个需求：运行 `hugo server` 时不加载分析代码；生产环境与预发环境使用不同的标记 ID。可以这样配置：

1. `config/_default/hugo.toml`：不写 `services.googleAnalytics` 区段。运行 `hugo server` 时 `environment` 默认为 `development`，在没有 `config/development` 目录的情况下 Hugo 使用 `config/_default`。
2. `config/production/hugo.toml`：只写 `[services.googleAnalytics]` 与 `ID = 'G-PPPPPPPPP'`。运行 `hugo build` 时 `environment` 默认为 `production`。
3. `config/staging/hugo.toml`：只写 `[services.googleAnalytics]` 与 `ID = 'G-SSSSSSSSS'`，用 `hugo build --environment staging` 构建预发站点。

环境目录中的文件只需写出与环境相关的设置，Hugo 会用它们覆盖默认配置中的同名键。

## 合并配置设置

Hugo 会合并来自主题与模块的配置，并优先使用项目自身的设置。这与用 `--config` 合并多个文件、或把配置拆分到配置目录不同：后两者对同名键总是直接覆盖。

以两个主题的项目为例：

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

```toml
baseURL = 'https://example.org/'
locale = 'en-us'
title = 'My New Hugo Site'
theme = ['theme-a','theme-b']
```

Hugo 按以下顺序合并设置：项目配置、`theme-a` 配置、`theme-b` 配置。

### 合并策略

每个配置分类中的 `_merge` 设置决定合并_哪些_设置以及_如何_合并。`_merge` 可以写在分类的任意嵌套层级，而不限于顶层；合并嵌套表时，Hugo 使用该表自身的 `_merge`，没有设置则继承最近的祖先。

```toml
[markup.goldmark.extensions.typographer]
_merge = 'deep'
```

`_merge` 的取值可以是：

- `none`：不合并。
- `shallow`：只为新键添加值。
- `deep`：为新键添加值，并合并已有键的值。

### 根级合并策略

`_merge` 也可以写在项目配置的根级（任何配置分类之外），从而改变整个项目的行为：

```toml
_merge = 'none'
baseURL = 'https://example.org/'
locale = 'en-us'
title = 'My New Hugo Site'
theme = ['theme-a','theme-b']
```

根级 `_merge` 为 `none` 时，主题与模块的配置完全不合并，无论各配置分类上写了什么；根级 `_merge` 为 `shallow` 或 `deep` 时，则改变那些未自行指定 `_merge` 的分类的默认合并策略。

> Hugo 可以把模块与主题中的映射（map）类型配置值合并进项目配置，但无法合并切片（slice）类型的值。这既包括 `menus` 这类切片类型的配置分类，也包括 `outputs` 中按页面种类划分的格式列表这类「值为切片」的映射键。

### 安全影响

多数配置分类默认采用 `none` 合并策略，正是为了保护项目免受第三方主题与模块的影响。

> 把 `_merge` 设为 `shallow` 或 `deep` 会移除这层保护，无论它作用于 `markup`、`security` 这类安全敏感的键，还是写在配置根级改变所有键的默认策略。只有在你信任项目中的每一个主题与模块时，才对这些键使用宽松的 `_merge`。

## 环境变量

也可以用操作系统环境变量来配置设置：

```bash
export HUGO_BASEURL=https://example.org/
export HUGO_ENABLEGITINFO=true
hugo
```

上例会设置 `baseURL` 与 `enableGitInfo`，然后构建站点。

> 环境变量的优先级高于配置文件中的值。也就是说，同一个配置项既用环境变量设置、又写在配置文件里时，Hugo 采用环境变量的值。

环境变量名必须以 `HUGO_` 开头；设置自定义站点参数时，前缀为 `HUGO_PARAMS_`。

对于 snake_case 形式的变量名，标准的 `HUGO_` 前缀不能直接用。Hugo 会根据 `HUGO` 之后的第一个字符推断分隔符，因此也可以写成 `HUGOxPARAMSxAPI_KEY=abcdefgh` 这样的形式。

除常规设置外，环境变量还可以覆盖某些内部设置的默认值：

- `DART_SASS_BINARY`：Dart Sass 可执行文件的绝对路径。默认情况下 Hugo 依次在 `PATH` 环境变量的各个路径中查找。
- `HUGO_ENVIRONMENT`：构建环境。运行 `hugo build` 时默认是 `production`，运行 `hugo server` 时默认是 `development`。
- `HUGO_FILE_LOG_FORMAT`：报错或从短代码、Markdown 渲染钩子调用 `Position` 方法时，文件路径、行号与列号的格式字符串；可用标记为 `:file`、`:line`、`:col`，默认为 `:file::line::col`。
- `HUGO_MEMORYLIMIT`：渲染站点时 Hugo 可用的最大系统内存，单位为 GB，默认是系统总内存的 25%。这是「尽力而为」的设置，可以用 `hugo build --logLevel info` 观察 `dynacache` 标签了解实际行为。
- `HUGO_NUMWORKERMULTIPLIER`：并行处理使用的工作进程数，默认等于逻辑 CPU 数量。

## 查看当前配置

查看完整的项目配置：

```bash
hugo config
```

查看某一项配置：

```bash
hugo config | grep [key]
```

查看已配置的文件挂载：

```bash
hugo config mounts
```