配置

全部设置

按键名索引 Hugo 全部顶层配置项,含类型、默认值与分区说明。

这一页解决什么问题

这一页是查键用的索引,不是教程:它回答「这个键叫什么、什么类型、默认值是多少、详细说明在哪一页」。具体怎么配、配错了会怎样,见配置章节首页与各分类页面。

怎么用它:先用浏览器页内搜索找到键名,再跳到对应分类页面读细节;拿到结论后,务必用 hugo config 核对本项目里实际生效的值——下表标注的默认值会随 Hugo 版本变化。

什么时候需要这些设置

下表挑出最常被改动、也最容易改错的顶层键(完整清单见下文各表):

键 什么时候需要 改错了会看到什么现象
baseURL 部署到真实域名之前必须改(默认是 https://example.org/) 忘记改 → 站内绝对链接、RSS、站点地图、Open Graph 全都指向示例域名,构建不报错
title / locale / timeZone 建站初期就该定下 timeZone 不设时,无时区日期的解析时区不确定;locale 影响日期、数字、货币的本地化
disableKinds 站点不使用分类法,想排除自动生成的空页面 种类名写错(例如写成 taxonomies)→ 没有效果,站点里照旧出现空的 /tags/ 这类页面
enableGitInfo 想让「最后更新」来自 Git 提交(配合 [frontmatter]) 开启但站点不是 Git 仓库、或文件尚未提交 → 日期回退链落空,Lastmod 可能落到零值
buildDrafts / buildFuture / buildExpired 本地预览草稿、未来或已过期内容 在生产配置里误开 → 未完成或已下线的内容被发布出去
publishDir 需要把产物输出到别的目录(如 docs/) 与部署脚本的约定不一致 → 部署了旧产物或空目录
theme 使用主题(多个主题时从左到右优先) 把它写在某个 [表头] 之后 → 变成 <表名>.theme 被静默忽略,报「找不到布局文件」
hasCJKLanguage 中文站点统计字数与摘要(本站已开启) 不开时中文的 WordCount 与摘要长度按「空格分词」计算,结果明显偏小
enableRobotsTXT 需要生成 robots.txt 不开启时没有 robots.txt,但站点地图仍会生成,搜索引擎可能找不到地图
ignoreLogs / panicOnWarning / printPathWarnings 想让构建暴露隐藏问题(CI 常用) panicOnWarning 开启后,原本只是警告的问题会让构建失败——先清掉存量警告再打开

本页是 Hugo 顶层配置键的索引,不是教程:它把项目配置中的每一个顶层键按名称字母序列出,并标注类型、默认值与一句话说明。请注意,这里的默认值只是上游文档在当前版本下的标注,精确默认值会随 Hugo 版本变化,请用 hugo config 或 hugo config mounts 核对你自己项目中实际生效的值。

每个顶层键要么是通用设置,即单个值,例如 baseURL 或 title;要么是配置分类,即把相关嵌套设置归为一组,例如 markup、menus 或 params。分类键的详情请见本站 configuration 章节下的对应页面(/configuration/…),没有单独页面的分类也在下表说明其用途。配置文件的基本写法与合并策略见配置 Hugo。

toml
baseURL = 'https://example.org/'
title = '我的站点'

[params]
  subtitle = '示例站点'

设置

通用设置

下表按上游顺序(字母序)列出全部通用设置。目录类键都会受模块挂载影响。

键 类型 默认值 说明
_merge string none 主题与模块配置的合并策略:none、shallow、deep。
archetypeDir string archetypes 原型文件目录。
assetDir string assets 全局资源目录,供资源管道读取。
baseURL string https://example.org/ 站点发布后的绝对 URL,需带结尾斜杠。
buildDrafts bool false 构建时是否包含草稿内容。
buildExpired bool false 构建时是否包含已过期内容。
buildFuture bool false 构建时是否包含未来日期的内容。
cacheDir string — 缓存目录,取值规则见下文「缓存目录」。
canonifyURLs bool false 是否把相对 URL 规范化为绝对 URL。
capitalizeListTitles bool true 是否自动大写分区、分类与术语列表标题。
cleanDestinationDir — — 已于 0.167.0 弃用,改由 build 分区控制。
contentDir string content 内容文件目录。
copyright string — 站点版权声明,通常显示在页脚。
dataDir string data 数据文件目录。
defaultContentLanguage string — 默认语言,须与已定义的语言键匹配。
defaultContentLanguageInSubdir bool false 是否把默认语言发布到同名子目录。
defaultContentRole string — 默认内容角色(0.153.0 新增)。
defaultContentRoleInSubdir bool false 是否把默认角色发布到同名子目录。
defaultContentVersion string — 默认内容版本(0.153.0 新增)。
defaultContentVersionInSubdir bool false 是否把默认版本发布到同名子目录。
defaultOutputFormat string — 默认输出格式,未设置时取首个可用格式。
disableAliases bool false 是否禁止为别名生成跳转文件。
disableDefaultLanguageRedirect bool false 是否禁止默认语言的重定向别名。
disableDefaultSiteRedirect bool false 是否禁止指向默认站点的重定向别名。
disableHugoGeneratorInject bool false 是否禁止向首页注入 generator 元标签。
disableKinds []string — 构建时禁用的页面类型列表。
disableLanguages []string — 构建时禁用的语言键列表。
disableLiveReload bool false 是否禁用浏览器自动实时重载。
disablePathToLower bool false 是否禁止把页面 URL 转为小写。
enableEmoji bool false 是否允许在 Markdown 中使用表情符号。
enableGitInfo bool false 是否读取 Git 提交信息供模板使用。
enableMissingTranslationPlaceholders bool false 缺少译文时是否显示占位符。
enableRobotsTXT bool false 是否生成 robots.txt 文件。
hasCJKLanguage bool false 是否自动识别中日韩语言以统计字数。
i18nDir string i18n 翻译表文件目录。
ignoreCache bool false 是否忽略已配置的文件缓存。
ignoreFiles []string — 用于排除文件的正则表达式列表。
ignoreLogs []string — 需要屏蔽的警告与错误消息标识列表。
ignoreVendorPaths string — 排除出 _vendor 目录的模块路径通配符。
languageCode — — 已于 0.158.0 弃用,请改用 locale。
layoutDir string layouts 模板文件目录。
locale string — RFC 5646 语言标签,用于翻译与本地化格式。
mainSections string 或 []string — 站点主要分区,供 MainSections 使用。
newContentEditor string — 新建内容时调用的编辑器。
noBuildLock bool false 是否禁止创建 .hugo_build.lock 文件。
noChmod bool false 是否禁止同步文件权限模式。
noTimes bool false 是否禁止同步文件修改时间。
panicOnWarning bool false 是否在出现首个警告时中断构建。
pluralizeListTitles bool true 是否自动把分区列表标题变为复数。
printI18nWarnings bool false 是否逐条记录缺失翻译的警告。
printPathWarnings bool false 多个文件写入同一路径时是否告警。
printUnusedTemplates bool false 是否为未使用的模板输出警告。
publishDir string public 站点发布目录。
refLinksErrorLevel string ERROR ref、relref 无法解析时的日志级别。
refLinksNotFoundURL string — ref、relref 无法解析时返回的 URL。
relativeURLs bool false 是否把站点 URL 转为相对路径。
removePathAccents bool false 是否移除内容路径中的组合字符重音。
renderSegments []string — 需要渲染的片段,省略则全部渲染。
resourceDir string resources 资源管道输出缓存目录。
sectionPagesMenu string — 指定菜单名,自动加入全部顶层分区。
staticDir string static 静态文件目录。
summaryLength int 70 自动摘要的最小词数。
templateMetrics bool false 是否在控制台输出模板执行指标。
templateMetricsHints bool false 是否输出模板执行优化提示。
theme string 或 []string — 所用主题,多个主题按从左到右优先。
themesDir string themes 主题目录。
timeout string 60s 生成页面内容的超时时间。
timeZone string — 解析无时区日期时使用的时区。
title string — 站点标题。
titleCaseStyle string ap 自动标题的大小写规则,见下文。

配置分类

下表列出全部分类键。它们本身没有类型与默认值,其下的嵌套键请见对应的独立页面。

键 类型 默认值 说明
build — — 构建与发布相关设置。
caches — — 各类文件缓存的配置。
cascade — — 级联前置元数据的配置。
deployment — — 部署目标与部署命令的配置。
frontmatter — — 前置元数据格式,见前置元数据配置。
HTTPCache — — HTTP 缓存策略,见 HTTP 缓存配置。
imaging — — 图像处理选项,见图像处理配置。
languages — — 多语言与本地化,见语言配置。
markup — — Markdown 与语法高亮,见标记配置。
mediaTypes — — 媒体类型定义。
menus — — 菜单定义,见菜单配置。
minify — — 输出压缩,见压缩配置。
module — — 模块与挂载,见模块配置。
outputFormats — — 输出格式定义,见输出格式配置。
outputs — — 各类页面可用的输出格式映射。
page — — 页面级默认设置。
pagination — — 分页行为,见分页配置。
params — — 自定义站点参数,见参数配置。
permalinks — — URL 结构,见永久链接配置。
privacy — — 第三方服务的隐私策略。
related — — 相关内容推荐规则。
roles — — 内容角色定义。
security — — 构建安全策略。
segments — — 构建片段,见片段配置。
server — — 开发服务器,见服务器配置。
services — — 第三方服务,见服务配置。
sitemap — — 站点地图,见站点地图配置。
taxonomies — — 分类法定义,见分类法。
uglyurls — — 是否使用不带目录的「丑陋」URL。
versions — — 内容版本定义。

缓存目录

缓存目录由 cacheDir 设置或环境变量 HUGO_CACHEDIR 决定。两者都未设置时,Hugo 按以下顺序择一使用:在 Netlify 上运行时用 /opt/build/cache/hugo_cache/,这样配置为 :cacheDir 的缓存能在下次构建时恢复;否则用操作系统用户缓存目录下的 hugo_cache 目录(Unix 为 $XDG_CACHE_HOME 或 $HOME/.cache,macOS 为 $HOME/Library/Caches,Windows 为 %LocalAppData%);再否则用系统临时目录下的 hugo_cache_$USER 目录。查看当前生效的 cacheDir:

bash
hugo config | grep cachedir

标题大小写风格

titleCaseStyle 控制自动生成的列表标题以及 strings.Title 函数的大小写规则,默认采用美联社写作风格手册的规则。

取值 说明
ap 默认值,遵循美联社写作风格手册。
chicago 遵循芝加哥格式手册。
go 每个单词的首字母都大写。
firstupper 仅首个单词的首字母大写。
none 不做任何转换,便于手动控制标题大小写。

本地化设置

menus、params 等设置可以针对每种语言分别定义,见语言配置。

常见坑

症状 真因 怎么修
表里查到的默认值和实际不符 默认值随 Hugo 版本变化,文档标注可能滞后 用 hugo config 看本项目实际生效的值
改了顶层键却完全没生效 键写在了某个 [表头] 之后,被 TOML 归入该表(例如 theme 变成 frontmatter.theme) 把所有裸键移到第一个表头之前
站点链接指向 example.org baseURL 还是默认值 改成真实域名,并保留结尾斜杠
中文摘要与字数明显偏少 hasCJKLanguage 未开启 设为 true
出现空的 /tags/、/categories/ 页面 没有使用分类法,却没有禁用对应页面类型 disableKinds = ['taxonomy','term'](本站即如此)
日期显示 0001-01-01 enableGitInfo 未开启,或没有可用的日期字段,回退链全部落空 见前置元数据配置
报错看不懂 顶层键的错误多来自拼写或类型不符 见故障排查

更多排查入口见故障排查。

相关页面