资源压缩
用 resources.Minify 压缩 CSS、JS、JSON、HTML、SVG 与 XML 资源。含支持的类型边界、完整示例与常见报错。
开始之前,你需要
- 读过简介,知道资源要经
.RelPermalink一类方法才会被发布 - 清楚管道顺序应为「转换 → 压缩 → 指纹」
读完之后你能
- 对支持的文本类型资源做压缩,并确认产物里注释与空白确实被去掉
- 说清
resources.Minify与命令行hugo --minify的区别 - 在压缩后表现异常时,知道先检查源文件是否依赖注释或空白
这一页解决什么问题
源文件里的注释、缩进与换行对人有用,对浏览器没用。压缩把这些字节去掉,让文件更小、加载更快,代价是产物不再适合阅读——所以调试时不要直接盯压缩后的文件,要看 source map 或原始文件。
resources.Minify 只处理文本类型:它不认识图片,也不做语法级别的优化(那是 js.Build 与 PostCSS 插件的事)。
方法签名与用途
resources.Minify 返回给定资源的最小化版本,参数就是资源对象:
resources.Minify RESOURCE它还有一个别名 minify,这也是管道写法中最常用的形式。两者完全等价:
{{ $css := resources.Get "css/main.css" }}
{{ $style := $css | minify }}返回值类型同样是 resource.Resource。可以压缩的资源类型为 CSS、JS、JSON、HTML、SVG 与 XML,其他类型不在支持范围内。
返回值与边界
| 情形 | 会怎样 |
|---|---|
| 支持的文本类型 | 返回压缩后的新资源,可继续 fingerprint 或发布 |
| 图片、字体等二进制资源 | 不在支持范围内;需要处理图片请用图像处理的缩放、裁剪等方法 |
上游是 nil(resources.Get 没取到) |
这一步失败,做法是先 with 判断资源存在 |
| 资源内容为空 | 得到一份空资源,发布出去是个 0 字节文件——通常说明取错了文件 |
| 已经是压缩产物 | 可以再压一次,但没有收益,只让管道更长 |
链式调用示例
最小化通常紧跟在构建或拼接之后、指纹之前:
{{ $main := resources.Get "css/main.scss" | css.Sass }}
{{ $style := $main | minify | fingerprint }}
<link rel="stylesheet" href="{{ $style.RelPermalink }}" integrity="{{ $style.Data.Integrity }}" crossorigin="anonymous">由字符串生成的资源也可以压缩,适合把少量样式直接内联到页面里:
{{ $content := printf "body{color:%s}" site.Params.color }}
{{ $r := resources.FromString "css/inline.css" $content | minify }}
<link rel="stylesheet" href="{{ $r.RelPermalink }}">发布时机
和其他 Hugo Pipes 的产物一样,压缩结果在你调用 Publish、Permalink 或 RelPermalink 时才会发布到 public 目录;不想生成文件而要把结果直接写进页面时,使用 .Content。
完整可运行示例
这个示例强调一件事:压缩去掉的到底是什么。
① 建项目并进入目录:
hugo new project minify-demo
cd minify-demo② 新建一份带注释和缩进的样式 assets/css/main.css:
/* 站点主样式:下面的注释与缩进都应当消失在产物里 */
body {
color: #222;
font-size: 18px;
}③ 新建首页模板 layouts/home.html:
{{ with resources.Get "css/main.css" }}
{{ with . | minify | fingerprint }}
<!doctype html>
<html lang="zh-cn">
<head>
<meta charset="utf-8">
<title>Minify 演示</title>
<link rel="stylesheet" href="{{ .RelPermalink }}" integrity="{{ .Data.Integrity }}" crossorigin="anonymous">
</head>
<body>
<h1>样式已压缩</h1>
</body>
</html>
{{ end }}
{{ end }}④ 构建:
hugo你应当看到什么
-
public/css/下出现main.<哈希>.css(没有设置targetPath时,沿用源文件名并加指纹); -
打开该文件,内容形如:
cssbody{color:#222;font-size:18px}注释、缩进与换行都不见了——这就是压缩生效的直接证据;
-
页面仍然正确显示(颜色与字号来自变量,与压缩无关);
-
注释掉
| minify再构建一次,产物会恢复成多行格式,并且文件名哈希随之变化:说明压缩确实改变了文件内容。
缓存与 –gc
Hugo Pipes 以整条管道链为缓存单位。同一条链在一次构建中只执行一次,之后都命中缓存,因此压缩虽然要消耗计算,但并不会随模板执行次数线性增长。链越长,首次执行的代价越高,这也是把构建、压缩、指纹放在同一条链里即可的原因。
hugo build --gc 会在构建完成后清理未使用的缓存文件。完整参数说明见命令。
什么时候用 / 什么时候别用
该用的时候
- 交付给浏览器的 CSS / JS / JSON / SVG / XML 体积敏感;
- 已经用
resources.Concat拼好一份资源,想在发布前压一次; - 想要「压缩 + 指纹」这一经典组合。
别用的时候
- 图片、字体、PDF 等二进制资源:压缩不是它们该走的环节,图片请用图像处理方法;
- 需要的是语法级优化(摇树、去掉死代码、转译新语法):用 js.Build;
- 需要对 CSS 做结构化处理(嵌套、前缀):用 PostCSS;
- 你正在调试:压缩后的文件难以阅读,调试时先把
minify这一环去掉,或依赖 source map。
常见坑
① 命令找不到(命令类)
hugo: command not found:先解决 Hugo 的安装与PATH,见安装 Hugo;- 压缩本身不调用任何外部命令,因此这一步出现的「找不到」类报错几乎都来自管道前面的环节(
css.Sass需要 Dart Sass、css.PostCSS需要 Node.js)。
② 没报错但结果不对(静默失败类)
| 现象 | 原因 | 怎么确认 |
|---|---|---|
public/ 里没有产物 |
结果没有被 .RelPermalink / .Permalink / .Publish 引用 |
看模板是否输出了标签 |
| 压缩产物是 0 字节 | 取到了空文件,或 resources.Get 的路径错了 |
打开源文件确认内容,核对相对 assets/ 的路径 |
| 页面样式/脚本行为变化 | 源文件依赖注释或空白(用注释当分隔、依赖自动分号插入) | 对比压缩前后的产物,给源文件补上显式分号 |
| 改了源文件,产物没变 | 管道链缓存未失效 | hugo --ignoreCache 重建 |
| 图片没有任何变化 | 图片不在支持的类型内 | 改用图像处理 |
③ 报错看不懂(报错类)
- 报错里出现
can't evaluate field一类「无法取值」:上游返回了nil,补上with; - 报错里出现
minify字样并伴随expected/unexpected:压缩器在对内容做语法解析时失败,问题在源文件语法,请先按浏览器或对应语言的规范修好源文件; - 报错的文件与你改的无关:渲染期问题(短代码、编码、配置)也会这样出现,见故障排查。
排查顺序:资源是否取到 → 类型是否受支持 → 源文件语法是否合法 → 缓存是否干扰。