Hugo缓存清理全面指南

一、第一步：停止所有 Hugo 进程（关键前置）

先关闭正在运行的 hugo server（终端按 Ctrl + C），并结束任务管理器中的 hugo.exe 进程，避免缓存文件被占用无法删除。

二、第二步：清理 Hugo 核心缓存（分 3 类）

1. 清理 Hugo 模块缓存（新版 Hugo 核心缓存）

这是 Hugo 存储第三方模块（如 FixIt 主题）的缓存，执行以下命令：

1
2
3
4
5

# 进入你的 docs 目录
cd E:\xxx\docs

# 清理所有模块缓存（适配 v0.154.2）
hugo mod clean --all

✅ 输出 Cleaned module cache 表示清理成功。

2. 清理 Hugo 全局文件缓存（Windows 系统）

Hugo 会在系统目录存储文件缓存，手动删除该目录：

1
2

# 删除 Hugo 全局缓存目录（Windows 专属）
Remove-Item -Path "$env:LOCALAPPDATA\hugo\cache" -Recurse -Force -ErrorAction SilentlyContinue

• 路径说明：%LOCALAPPDATA%\hugo\cache 是 Hugo 默认的全局缓存目录，包含模板、静态文件等缓存。

3. 清理旧的构建产物（public 目录）

删除之前构建生成的静态文件，确保重新构建时生成全新文件：

1
2

# 删除 public 目录（Hugo 默认构建输出目录）
Remove-Item -Path "E:\xxxx\docs\public" -Recurse -Force -ErrorAction SilentlyContinue

三、第三步：重新构建站点（2 种场景）

场景 1：本地开发调试（带实时预览）

1
2

# 禁用缓存启动服务器，强制重新构建所有文件
hugo server --ignoreCache --disableFastRender

• --ignoreCache：禁用 Hugo 运行时缓存，强制重新渲染所有页面；
• --disableFastRender：关闭快速渲染模式，确保文件变更时完全重建（而非增量重建）。

场景 2：生产环境构建（生成静态文件）

1
2

# 强制重新构建并压缩文件（无缓存）
hugo --minify --ignoreCache

• --minify：压缩 HTML/CSS/JS 文件，适合部署上线；
• 构建产物会生成到 public 目录，可直接用于部署。

核心原理说明

1. hugo mod clean --all：清理 Hugo 模块仓库的缓存，解决 FixIt 主题版本/模板缓存残留问题；
2. %LOCALAPPDATA%\hugo\cache：清理 Hugo 存储的模板编译缓存、静态文件缓存，解决「修改模板不生效」问题；
3. --ignoreCache：运行时禁用缓存，确保每次构建都读取最新的配置、主题和内容文件。

验证缓存清理成功

重新构建后，终端会显示：

• 开发模式：Built in XXX ms（耗时比平时稍长，因为重新编译所有模板）；
• 生产模式：public 目录下生成全新的静态文件，无旧文件残留；
• 之前的模板警告/渲染错误（如 no layout file）会消失（若配置正确）。

总结

关键点回顾

1. 清理缓存三步核心：模块缓存 → 全局文件缓存 → 旧构建产物；
2. 重新构建时添加 --ignoreCache，确保不使用任何缓存；
3. 开发用 hugo server --ignoreCache --disableFastRender，生产用 hugo --minify --ignoreCache。

[[../tool/Obsidian文章属性自动化管理完全指南]]