缓存配置
配置文件缓存的用途、键、路径标记与垃圾回收。
这一页解决什么问题
Hugo 会把「算过一次的结果」写到磁盘上,避免重复劳动——图片处理、远程资源下载、Sass 编译、模块解析都走这套缓存。这一页说明缓存放在哪、什么时候过期、以及缓存作祟时怎么清干净。
关键提醒:这里改错通常不会报错,只会表现为「源文件改了但产物没变」或者磁盘被缓存吃满。遇到「改了没反应」,先用 hugo --ignoreCache 构建一次做对照,再回来查这一页。
什么时候需要这些设置
| 设置 | 什么时候需要 | 改错了会看到什么现象 |
|---|---|---|
dir |
想换缓存位置(磁盘紧张、CI 需要缓存目录可保留) | 路径不存在或无写权限 → 缓存相关操作直接失败;指到项目内且被清理波及 → 缓存每次都被清 |
maxAge |
想定期淘汰远程资源或图片处理结果 | 0 表示禁用该组缓存(每次构建重新下载/处理,构建明显变慢);-1 表示永不过期(缓存只增不减,getresource 与 misc 尤其明显) |
modulegitinfo / modulequeries |
使用 Hugo Modules,且不想每次构建都联网校验 | maxAge 调大后,模块仓库的更新不会立刻反映到构建中 |
什么时候别用:不要把 maxAge 一律设成 -1 来「提速」。缓存不失效的问题应该修在源头(例如 build.cacheBusters,见构建配置),而不是让旧值永远留着。
默认配置
toml
[caches]
[caches.assets]
dir = ':resourceDir/_gen'
maxAge = -1
[caches.getresource]
dir = ':cacheDir/:project'
maxAge = -1
[caches.images]
dir = ':resourceDir/_gen'
maxAge = -1
[caches.misc]
dir = ':cacheDir/:project'
maxAge = -1
[caches.modulegitinfo]
dir = ':cacheDir/modules'
maxAge = '24h'
[caches.modulequeries]
dir = ':cacheDir/modules'
maxAge = '24h'
[caches.modules]
dir = ':cacheDir/modules'
maxAge = -1用途
Hugo 用文件缓存把数据保存在磁盘上,既避免同一次构建中重复执行相同操作,也让数据可以跨构建持续保留。
| 键名 | 类型 | 默认值 | 说明 |
|---|---|---|---|
assets |
map |
见上文 | 缓存已处理的 CSS 与 Sass 资源。 |
getresource |
map |
见上文 | 缓存通过 resources.GetRemote 函数从远程 URL 获取的文件。 |
images |
map |
见上文 | 缓存已处理的图片。 |
misc |
map |
见上文 | 缓存杂项数据,例如 transform.ToMath 函数的结果。 |
modulegitinfo |
map |
见上文 | 缓存模块的 Git 信息。 |
modulequeries |
map |
见上文 | 缓存模块解析查询的结果。 |
modules |
map |
见上文 | 缓存已下载的模块。 |
键
每个缓存分组都支持以下两个键:
| 键名 | 类型 | 默认值 | 说明 |
|---|---|---|---|
dir |
string |
见上文 | Hugo 存放缓存文件的绝对文件系统路径。路径可以以 :cacheDir 或 :resourceDir 标记开头,把缓存锚定到特定的系统或项目位置。 |
maxAge |
string |
-1 |
缓存条目在被清除前保持有效的时长,用时长表示。值为 0 表示对该键禁用缓存,值为 -1 表示缓存条目永不过期。 |
路径标记
| 标记 | 类型 | 说明 |
|---|---|---|
:cacheDir |
string |
指定的缓存目录,即 cacheDir 设置的值。 |
:project |
string |
当前 Hugo 项目的基础目录名。这可以确保每个项目有独立的文件缓存,避免 hugo build --gc 命令影响同一台机器上的其他项目。 |
:resourceDir |
string |
用于缓存资源管道产物的指定目录,即 resourceDir 设置的值。 |
例如 dir = ':cacheDir/:project' 表示把缓存放在 cacheDir 之下、以项目目录名命名的子目录中;dir = ':resourceDir/_gen' 表示放在项目资源目录的 _gen 子目录中。
垃圾回收
随着你修改站点或更改配置,先前构建留下的缓存文件可能继续占用磁盘空间。使用 hugo build --gc 命令可以从文件缓存中删除这些已过期或不再使用的条目。
常见坑
| 症状 | 真因 | 怎么修 |
|---|---|---|
| 改了图片处理参数或 Sass,产物没变化 | 命中了旧的缓存条目 | 先用 hugo --ignoreCache 构建对照一次;确认是缓存问题后,删除 :cacheDir / :resourceDir 下的缓存目录 |
resources.GetRemote 拿到的还是旧内容 |
getresource 组缓存仍然有效 |
删除该组缓存目录(默认 :cacheDir/:project),或把它的 maxAge 调小 |
| 磁盘被缓存占满 | maxAge = -1 表示永不过期,缓存只增不减 |
定期执行 hugo build --gc;增长快的分组改设有限 maxAge |
| CI 上每次构建都很慢 | 缓存目录没有被跨构建保留 | 把 cacheDir 指向 CI 的缓存目录并纳入缓存策略;当前默认位置可用 hugo config 的 cachedir 查看 |
| 缓存目录写不进去 | dir 指向不存在的盘符或没有权限的路径 |
改用绝对路径并确认权限;跨机器场景避免把绝对路径写死 |
更多排查入口见故障排查。