资源打包
用 resources.Concat 把多个同类型资源拼接为一份资源并发布。含顺序控制、完整示例、返回值边界与常见报错。
开始之前,你需要
- 读过简介,知道
assets/里的文件要先resources.Get取成资源 - 能写出
slice、管道与with这几个最基本的 Go 模板写法
读完之后你能
- 把多个同类型资源按确定的顺序拼成一份,并说明目标路径同时也是缓存键与发布路径
- 判断什么时候值得拼接、什么时候反而应该让浏览器分别缓存各文件
- 在拼接结果缺失或顺序不对时,按「资源是否为 nil → 顺序是否正确 → 缓存是否干扰」排查
这一页解决什么问题
把十几份 CSS 或 JS 分别用 <link> / <script> 引入,意味着十几个请求,也意味着依赖顺序要靠人肉保证。resources.Concat 把这些文件按你给的顺序拼成一份资源,再交给压缩与指纹环节。
它只做一件事:文本层面的连接。不做语法分析、不补分号、不去重,这些都由后续环节或你自己的书写规范负责。
方法签名与用途
resources.Concat 把一个资源切片拼接为一份资源,并以目标路径作为缓存键。签名如下:
resources.Concat TARGETPATH [RESOURCE...]返回值类型是 resource.Resource,因此拼接结果可以继续接入 Hugo Pipes 的其他环节。切片中的每个资源必须具有相同的媒体类型;媒体类型不同的资源不能拼接在一起。
返回值与边界
| 情形 | 会怎样 |
|---|---|
| 正常拼接 | 返回一个新的 resource.Resource,可以继续 minify / fingerprint |
| 切片里混入不同媒体类型(CSS 与 JS) | 不产生可用的样式表或脚本,浏览器会在解析时报错 |
切片里某项是 nil(对应的 resources.Get 没取到) |
这一步会失败,不会被静默跳过;用 with 先确认每个资源都存在 |
| 只拼接一份资源 | 结果可用,但没有意义:等于给同一份内容换了个名字 |
| 目标路径为空 | 没有可用的发布路径,不要这样写 |
基本用法
先用 resources.Get 从 assets 目录取回资源,再用 slice 组成切片传给 resources.Concat:
{{ $plugins := resources.Get "js/plugins.js" }}
{{ $global := resources.Get "js/global.js" }}
{{ $js := slice $plugins $global | resources.Concat "js/bundle.js" }}拼接后的内容顺序与切片中资源的顺序一致,所以要根据依赖关系安排 slice 的参数次序,例如先放第三方库,再放站点自身的脚本。
为什么顺序是硬要求:拼接是纯文本连接。若 plugins.js 里定义了一个 jQuery 插件、而 global.js 一开头就调用它,顺序颠倒就会在浏览器控制台报 undefined is not a function——构建阶段不会有任何提示。
与压缩、指纹组合
拼接结果仍是资源对象,可以接着做压缩与指纹:
{{ $reset := resources.Get "css/reset.css" }}
{{ $main := resources.Get "css/main.css" }}
{{ $css := slice $reset $main | resources.Concat "css/bundle.css" | minify | fingerprint }}
<link rel="stylesheet" href="{{ $css.RelPermalink }}" integrity="{{ $css.Data.Integrity }}" crossorigin="anonymous">压缩与指纹的含义分别见资源压缩与资源指纹,本节只讨论拼接环节。
发布时机
拼接结果不会自动写入 public 目录。只有调用它的 Publish、Permalink 或 RelPermalink 方法时,Hugo 才会把资源发布到目标路径。因此模板中至少要引用一次结果,例如把 RelPermalink 放进 link 或 script 标签。若想直接把内容内联进页面,可以改用 .Content。
完整可运行示例
这个示例把两份 CSS 拼成一份,并验证「顺序确实按你写的来」。
① 建项目并进入目录:
hugo new project concat-demo
cd concat-demo② 新建第一份样式 assets/css/reset.css:
body {
margin: 0;
}③ 新建第二份样式 assets/css/main.css:
body {
background-color: #fefefe;
color: #222;
}④ 新建首页模板 layouts/home.html:
{{ $reset := resources.Get "css/reset.css" }}
{{ $main := resources.Get "css/main.css" }}
{{ with slice $reset $main | resources.Concat "css/bundle.css" | minify | fingerprint }}
<!doctype html>
<html lang="zh-cn">
<head>
<meta charset="utf-8">
<title>Concat 演示</title>
<link rel="stylesheet" href="{{ .RelPermalink }}" integrity="{{ .Data.Integrity }}" crossorigin="anonymous">
</head>
<body>
<h1>两份样式已拼成一份</h1>
</body>
</html>
{{ end }}⑤ 构建并查看:
hugo你应当看到什么
public/css/下只出现一个bundle.<哈希>.css,而没有reset.css或main.css——拼接结果才是被引用的那个资源;- 打开该文件,
body{margin:0}出现在body{background-color:#fefefe;...}之前。顺序与slice参数一致,这就是顺序控制的验证; - 页面源代码里
<link>的href带哈希,且integrity属性存在; - 把
slice的两个参数对调后重新hugo,文件内容顺序随之颠倒,哈希值也随之变化——哈希变了说明发布出去的确实是一份新文件。
用 hugo server 预览时,还可以在开发者工具的 Network 面板确认:整页只加载了一个 CSS 请求。
缓存与 –gc
Hugo Pipes 以整条管道链为缓存单位:同一条链在一次站点构建中只执行一次,其余调用直接读取缓存;resources.Concat 另外用目标路径作为缓存键。所以同一个目标路径的拼接结果会被复用,适合在多个模板中引用同一份打包资源。
构建时可以用 hugo build --gc 在构建完成后清理未使用的缓存文件,减小缓存目录体积。目标目录中的陈旧文件属于另一类问题,需要通过清理发布目录的参数处理,详见命令与基本用法。
什么时候用 / 什么时候别用
该用的时候
- 一批文件必须按固定顺序加载(第三方库在前、站点代码在后),你希望这个顺序只写一次、写在模板里;
- 文件数量多,希望减少请求数;
- 需要把拼接结果再压缩、加指纹后作为单文件交付。
别用的时候
- 媒体类型不同:CSS 与 JS 不能拼在一起,按类型分别打包;
- 文件本来就少(两三份),且它们各自更新频率不同:分开命名反而能让浏览器只重新下载改动过的那一份;
- 只想把内容内联到页面里:
resources.FromString或.Content更直接; - 希望自动处理依赖顺序:
resources.Concat不懂模块依赖,那类需求交给 js.Build(它按import图排序打包)。
常见坑
① 命令找不到(命令类)
hugo: command not found:Hugo 没装或没进PATH,先看安装 Hugo;- 命令本身没有外部依赖,因此拼接这一环不会出现「缺某个可执行文件」的报错;如果报错里有别的工具名,问题多半在管道前后(例如
css.Sass或postcss那一段)。
② 没报错但结果不对(静默失败类)
| 现象 | 原因 | 怎么确认 |
|---|---|---|
public/ 里没有打包结果 |
结果没被 .Permalink / .RelPermalink / .Publish 引用 |
模板里是否输出了 <link> 或 <script> |
| 页面样式只生效了一部分 | slice 里某个 resources.Get 返回了 nil,或顺序颠倒 |
分别检查每个路径是否相对 assets/ |
| 改了一个源文件,整体没变 | 目标路径缓存键未失效,或构建缓存未失效 | 先确认管道输入变了,再 hugo --ignoreCache 重建 |
拼接处语法错误(如 }body{) |
某个源文件末尾缺少换行或分号,纯文本连接后与下一份粘连 | 打开产物看接缝处,给源文件补上换行 |
引用了 bundle.css 却 404 |
页面里写的是 RelPermalink 之前的裸路径,或目标路径写错 |
以页面源代码中的实际 href 为准 |
③ 报错看不懂(报错类)
- 报错说某个变量「无法取值」(
can't evaluate field):说明上游有函数返回了nil,往回找哪个resources.Get没取到; - 报错里出现
expected resource.Resource一类类型不符:slice里混进了字符串或nil,确认每一项都是资源对象; - 样式/脚本在浏览器控制台报错、构建却成功:拼接与压缩都不会做语法检查,问题在源文件内容;
- 报错指向的文件与你改的无关:渲染期问题常这样出现,见故障排查。
排查顺序:每份资源是否取到 → 顺序是否与依赖一致 → 源文件接缝处是否有换行 → 缓存是否干扰。