Hugo 缓存策略配置¶

问题说明¶

useResourceCacheWhen 的三个值¶

Hugo 的 useResourceCacheWhen 配置有三个值：

值	行为	适用场景
`never`	从不使用缓存	调试缓存问题
`fallback`	首选源文件，不存在时用缓存	本地开发 ✓
`always`	优先使用缓存	生产构建 ✓

遇到的问题¶

当在配置文件中设置 useResourceCacheWhen = "always" 后，本地开发会报错：

ERROR POSTCSS: failed to transform "/css/combined.css" (text/css): 
resource "css/combined.css_xxx" not found in file cache

原因：

always 策略要求缓存必须存在
本地运行 npm run clean:cache 删除了缓存
Hugo 尝试从缓存加载资源但找不到
构建失败 ❌

解决方案¶

方案：环境变量 + fallback 默认值¶

配置文件（config/_default/config.toml）：

[build]
# 本地开发使用 fallback（首选源文件）
useResourceCacheWhen = "fallback"

Cloudflare Pages 环境变量：

Name: HUGO_RESOURCECACHEWHEN
Value: always
Environment: Production

工作原理：

本地开发：使用 fallback，清理缓存后可以正常构建
生产环境：环境变量覆盖配置，使用 always，利用缓存加速

配置步骤¶

1. 修改配置文件¶

config/_default/config.toml：

[build]
# 缓存策略：
# - "fallback": 首选源文件，源文件不存在时使用缓存（本地开发推荐）
# - "always": 优先使用缓存（Cloudflare Pages 生产环境通过环境变量设置）
# 本地开发使用 fallback 避免缓存问题
# 生产环境通过 HUGO_RESOURCECACHEWHEN=always 环境变量使用 always
useResourceCacheWhen = "fallback"

# Hugo 缓存配置 - 加速重复构建
[caches]
  [caches.getjson]
    dir = ":resourceDir/_cache/getjson"
    maxAge = "24h"

  [caches.images]
    dir = ":resourceDir/_cache/images"
    maxAge = "168h"

  [caches.assets]
    dir = ":resourceDir/_cache/assets"
    maxAge = "168h"

  [caches.modules]
    dir = ":cacheDir/modules"
    maxAge = "168h"

2. 配置 Cloudflare Pages¶

进入：Dashboard → Pages → jimmysong.io → Settings → Environment variables

添加两个环境变量：

a. Python 依赖优化¶

在生产构建中，如果不需要安装完整的本地开发 Python 依赖，可以通过环境变量跳过安装：

Name: SKIP_DEPENDENCY_INSTALL
Value: true
Environment: Production

然后在构建脚本中根据该变量有条件地安装依赖，例如：

if [ "$SKIP_DEPENDENCY_INSTALL" != "true" ]; then
  pip install -r requirements.txt
else
  echo "SKIP_DEPENDENCY_INSTALL=true - skipping python dependency installation"
fi

b. Hugo 缓存策略¶

Name: HUGO_RESOURCECACHEWHEN
Value: always
Environment: Production

验证¶

本地开发¶

# 清理缓存后构建应该成功
npm run clean:cache
npm run build
# ✅ 成功！使用 fallback 策略

# 再次构建（有缓存）也应该成功
npm run build
# ✅ 成功！使用缓存加速

Cloudflare Pages¶

查看构建日志：

...
Hugo environment: production
HUGO_RESOURCECACHEWHEN=always  ← 环境变量生效
...
Start building sites …
...
Total in 60000-70000 ms  ← 使用缓存，快！

缓存目录结构¶

resources/
├── _cache/           # Hugo 缓存（由我们配置）
│   ├── getjson/      # JSON 数据缓存
│   ├── getcsv/       # CSV 数据缓存
│   ├── images/       # 图片处理缓存
│   ├── assets/       # SCSS/JS 编译缓存
│   └── modules/      # Hugo 模块缓存
└── _gen/             # Hugo 生成的资源（自动）
    ├── assets/       # 编译后的 CSS/JS
    └── images/       # 处理后的图片

不同场景的行为¶

场景 1：本地首次构建¶

npm run clean:cache  # 删除 resources/ 和 public/
npm run build

行为：

useResourceCacheWhen = "fallback"
没有缓存，从源文件处理
生成资源到 resources/_gen/
保存缓存到 resources/_cache/
✅ 构建成功

场景 2：本地重复构建¶

npm run build  # 不清理缓存

行为：

useResourceCacheWhen = "fallback"
优先从源文件处理（fallback 策略）
如果源文件未变化，使用缓存
✅ 构建成功，有一定加速

场景 3：Cloudflare Pages 首次构建¶

npm run build  # 在 CF Pages 环境

行为：

HUGO_RESOURCECACHEWHEN=always 环境变量覆盖配置
没有缓存，从源文件处理（always 策略的 fallback）
生成并保存缓存
Cloudflare Pages 缓存 resources/ 目录
✅ 构建成功

场景 4：Cloudflare Pages 后续构建¶

npm run build  # 在 CF Pages 环境

行为：

Cloudflare Pages 恢复 resources/ 缓存
HUGO_RESOURCECACHEWHEN=always
优先使用缓存，跳过重复处理
只处理变化的文件
✅ 构建成功，显著加速！

性能对比¶

场景	缓存策略	Hugo 构建时间
本地开发	fallback	~30 秒（小项目）
本地开发	fallback + 缓存	~25 秒
CF Pages 首次	always（无缓存）	~85 秒
CF Pages 后续	always + 缓存	~60-70 秒 ✓

故障排查¶

问题 1：本地报错 "not found in file cache"¶

原因：配置文件中使用了 always 策略

解决：

# 1. 改回 fallback
vim config/_default/config.toml
# useResourceCacheWhen = "fallback"

# 2. 清理缓存重新构建
npm run clean:cache
npm run build

问题 2：Cloudflare Pages 没有使用缓存¶

检查：

环境变量 HUGO_RESOURCECACHEWHEN=always 是否设置
构建日志中是否显示环境变量
Hugo 构建时间是否减少

解决：

在 Cloudflare Pages Dashboard 添加环境变量
确保设置在 Production 环境
保存并触发新构建

问题 3：缓存配置不生效¶

检查：

# 查看 Hugo 版本
hugo version
# 需要 v0.147.8+

# 查看缓存目录
ls -la resources/_cache/

确认配置：

[caches]
  [caches.images]
    dir = ":resourceDir/_cache/images"  # 路径正确
    maxAge = "168h"                     # 过期时间合理

最佳实践¶

1. 本地开发¶

# 正常构建（保留缓存）
npm run build

# 遇到问题时清理缓存
npm run build:clean

2. 生产部署¶

# 确保配置
# 1. config.toml: useResourceCacheWhen = "fallback"
# 2. CF Pages 环境变量: HUGO_RESOURCECACHEWHEN=always

# 推送代码
git push origin main

# Cloudflare Pages 自动构建，使用缓存优化

3. 调试缓存¶

# 查看缓存内容
ls -la resources/_cache/*/

# 查看缓存大小
du -sh resources/_cache/

# 完全清理
npm run clean:full
npm install
npm run build

环境变量优先级¶

Hugo 配置优先级（从高到低）：

环境变量：HUGO_RESOURCECACHEWHEN=always
配置文件：config.toml 中的 useResourceCacheWhen
默认值：fallback

这就是为什么我们可以：

配置文件使用 fallback（本地开发友好）
生产环境用环境变量覆盖为 always（性能优化）

总结¶

最佳配置方案：

配置文件：useResourceCacheWhen = "fallback"
本地开发友好
清理缓存后可以正常构建
Cloudflare Pages 环境变量：HUGO_RESOURCECACHEWHEN=always
生产环境优化
利用缓存加速构建

这样既保证了本地开发的灵活性，又实现了生产环境的性能优化！🎉