css

css.Build

返回把给定 CSS 资源打包、转换并压缩后生成的资源。

签名
css.Build [OPTIONS] RESOURCE
返回类型
resource.Resource

(0.158.0 新增)

用 css.Build 函数可以:

  • 递归地把 CSS 文件中的 @import 语句替换为被导入文件的内容
  • 为兼容浏览器做语法转换
  • 为兼容浏览器添加厂商前缀
  • 压缩打包后的 CSS 代码
  • 生成 source map

若 @import 语句带有媒体查询、特性查询或级联层(cascade layer)赋值,该函数会把导入的内容包进对应的 @media、@supports 或 @layer 规则中。

这一页解决什么问题

项目里的 CSS 往往不是一个文件:基础样式、组件样式分开放,靠 @import 串起来;上线前还想压缩、补浏览器前缀。css.Build 用内嵌的 esbuild 一次做完这些事——递归内联 @import、按目标浏览器转换语法与补前缀、生成 source map、压缩——并返回一个资源(Resource),照常接进 <link> 或继续 fingerprint。

它和另外两个「CSS 管道」的分工是本站最常被问到的:css.Build 处理纯 CSS,css.Sass 编译 Sass/SCSS,css.PostCSS 交给 PostCSS 插件。

什么时候用,什么时候别用

该用:

  • 把多个 CSS 文件合并成一个(处理 @import);
  • 需要按目标浏览器降级语法、补厂商前缀,或压缩 CSS;
  • 想用 vars 选项往 CSS 里注入值(配合 @import 'hugo:vars')。

别用:

  • 写的是 Sass/SCSS → 用 css.Sass;Tailwind CSS v4 → 用 css.TailwindCSS;
  • 依赖 PostCSS 生态插件 → 用 css.PostCSS;
  • 只是把 assets/ 里的 CSS 原样发布 → 直接 resources.Get 加 .RelPermalink 即可,不必多一道构建。

用法

下例中,Hugo 把 @import 语句引用的本地文件打包成一份资源,并以内容内联的方式发布。

tree
assets/
└── css/
    ├── components/
    │   ├── a.css
    │   └── b.css
    └── main.css
assets/css/main.csscss
@import url('https://cdn.jsdelivr.net/npm/the-new-css-reset/css/reset.min.css');

@import './components/a.css';
@import './components/b.css';

.c {color: blue; }
assets/css/components/a.csscss
.a { color: red; }
assets/css/components/b.csscss
.b { color: green; }
layouts/_partials/css.htmlgo-html-template
{{ with resources.Get "css/main.css" | css.Build }}
  {{ if hugo.IsDevelopment }}
    <link rel="stylesheet" href="{{ .RelPermalink }}">
  {{ else }}
    {{ with . | fingerprint }}
      <link rel="stylesheet" href="{{ .RelPermalink }}" integrity="{{ .Data.Integrity }}" crossorigin="anonymous">
    {{ end }}
  {{ end }}
{{ end }}
layouts/baseof.htmlgo-html-template
{{ partialCached "css.html" . }}

生成的 CSS 代码:

public/css/main.csscss
@import "https://cdn.jsdelivr.net/npm/the-new-css-reset/css/reset.min.css";

.a {
  color: red;
}

.b {
  color: green;
}

.c {
  color: blue;
}

要压缩生成的 CSS 代码,请使用下文所述的 minify 选项。

选项

css.Build 函数接受一个选项映射,用于微调打包、压缩与浏览器兼容性。

externals
([]string) 要从打包中排除的路径模式切片。这些模式对应的 @import 语句会在生成的 CSS 代码中原样保留。参见详情。
go-html-template
{{ $opts := dict "externals" (slice "./exclude-these/*" "./exclude-these-too/*") }}
{{ $r := resources.Get "css/main.css" | css.Build $opts }}
importContext
(0.165.0 新增)
(resource.ResourceGetter) 解析 @import 语句时使用的资源获取器。Hugo 先按 @import 语句中书写的路径在这个上下文中查找,找不到再回退到文件系统。
loaders
(map) 文件扩展名到加载器类型的映射,用于决定打包时如何处理具有给定扩展名的文件。默认情况下,Hugo 对 .css 文件使用 css 加载器,对其余文件使用 file 加载器。常用加载器包括:
  • css:把文件作为 CSS 文件处理
  • dataurl:把文件以内嵌的 base64 数据 URL 形式嵌入
  • empty:把文件排除在打包结果之外
  • file:把文件复制到输出目录并改写其 URL
  • text:把文件内容作为字符串加载

参见详情。

go-html-template
{{ $opts := dict "loaders" (dict ".png" "dataurl" ".svg" "dataurl") }}
{{ $r := resources.Get "css/main.css" | css.Build $opts }}
mainFields
([]string) package.json 文件中用于确定 Node 包 CSS 入口点的字段名切片,按优先级排列。默认是 ["style", "main"]。参见详情。

当 @import 语句引用某个 Node 包时,Hugo 会查阅该包 package.json 中的元数据来查找样式表。若某个包用非标准字段定义 CSS 入口点,可用这个选项支持它。

go-html-template
{{ $opts := dict "mainFields" (slice "css" "style" "main") }}
{{ $r := resources.Get "css/main.css" | css.Build $opts }}
minify
(bool) 是否压缩生成的 CSS 代码。默认是 false。参见详情。
go-html-template
{{ $opts := dict "minify" true }}
{{ $r := resources.Get "css/main.css" | css.Build $opts }}
sourceMap
(string) 要生成的 source map 类型,取 external、inline、linked、none 之一。默认是 none。参见详情。
go-html-template
{{ $opts := dict "sourceMap" "linked" }}
{{ $r := resources.Get "css/main.css" | css.Build $opts }}
sourcesContent
(bool) 是否在 source map 中包含源文件的内容。默认是 true。参见详情。
go-html-template
{{ $opts := dict "sourceMap" "linked" "sourcesContent" false }}
{{ $r := resources.Get "css/main.css" | css.Build $opts }}
target
([]string) 生成的 CSS 代码的目标环境,用于决定执行哪些语法转换、添加哪些厂商前缀。不设置时不做任何转换或加前缀。每个元素由目标名称与版本号组成。支持的目标包括 chrome、edge、firefox、ie、ios、opera、safari。参见详情。
go-html-template
{{ $target := slice "chrome115" "edge115" "firefox116" "ios16.4" "opera101" "safari16.4" }}
{{ $opts := dict "target" $target }}
{{ $r := resources.Get "css/main.css" | css.Build $opts }}

上述目标环境大致相当于截至 2026 年 3 月 browserlist 的「baseline widely available」配置。

targetPath
(string) 资源的目标路径,相对于 publishDir。不设置时,目标路径默认为该资源原路径并把扩展名改为 .css。
go-html-template
{{ $opts := dict "targetPath" "css/styles.css" }}
{{ $r := resources.Get "css/main.css" | css.Build $opts }}
vars
(0.160.0 新增)
(map) 用于生成 CSS 变量的键值对映射。当 css.Build 函数在 @import 语句中遇到 hugo:vars 这个内部标识符时,会把这些变量注入样式表。
go-html-template
{{ $vars := dict
  "font-family" "\"Times New Roman\", Times, serif"
  "font-size" "24px"
  "primary-color" "blue"
}}
{{ $opts := dict "vars" $vars }}
{{ $r := resources.Get "css/main.css" | css.Build $opts }}

在上例中,只要在 CSS 里使用该标识符,就能用标准 CSS 变量语法访问这些值。

css
@import 'hugo:vars';

.element {
  color: var(--primary-color);
  font-family: var(--font-family);
  font-size: var(--font-size);
}

上面的写法会生成等价于下述内容的输出:

css
:root {
  --font-family:
    "Times New Roman",
    Times,
    serif;
  --font-size: 24px;
  --primary-color: blue;
}

.element {
  color: var(--primary-color);
  font-family: var(--font-family);
  font-size: var(--font-size);
}

(0.161.0 新增)

该映射可选地包含嵌套映射。每个嵌套映射会作为一个独立的 hugo:vars/<name> 命名空间暴露出来,其中 <name> 是嵌套映射的键(转为小写)。顶层的标量值与嵌套映射彼此独立:顶层的 @import 'hugo:vars' 只包含标量值,而 @import 'hugo:vars/<name>' 只包含指定嵌套映射中的标量。

go-html-template
{{ $vars := dict
  "font-family" "\"Times New Roman\", Times, serif"
  "font-size" "24px"
  "primary-color" "blue"
  "mobile" (dict
    "font-size" "12px"
    "primary-color" "red"
  )
}}
{{ $opts := dict "vars" $vars }}
{{ $r := resources.Get "css/main.css" | css.Build $opts }}

由于嵌套导入遵循与普通 @import 语句相同的规则,你可以给 hugo:vars/<name> 导入附加媒体查询、特性查询或级联层赋值。

css
@import 'hugo:vars';
@import 'hugo:vars/mobile' (max-width: 650px);

body {
  background-color: var(--primary-color);
  font-family: var(--font-family);
}

上面的写法会生成等价于下述内容的输出:

css
:root {
  --font-family: "Times New Roman", Times, serif;
  --font-size: 24px;
  --primary-color: blue;
}

@media (max-width: 650px) {
  :root {
    --font-size: 12px;
    --primary-color: red;
  }
}

body {
  background-color: var(--primary-color);
  font-family: var(--font-family);
}

在项目配置中设置 CSS 变量时,vars 选项很有用。

toml
[params.theme.style]
font-family = '"Times New Roman", Times, serif'
font-size = '24px'
primary-color = 'blue'

[params.theme.style.mobile]
font-size = '12px'
primary-color = 'red'
go-html-template
{{ $opts := dict "vars" site.Params.theme.style }}
{{ $r := resources.Get "css/main.css" | css.Build $opts }}

向 css.Build 函数传入 vars 映射时,可以用 css.Quoted 函数明确表示某个值必须当作带引号的字符串处理,最常用于 font-family 名称或 content 属性。

示例

下例使用上文介绍的若干选项来打包、转换并压缩 CSS 代码。

layouts/_partials/css.htmlgo-html-template
{{ with resources.Get "css/main.css" }}
  {{ $opts := dict
    "loaders" (dict ".png" "dataurl" ".svg" "dataurl")
    "minify" (cond hugo.IsDevelopment false true)
    "sourceMap" (cond hugo.IsDevelopment "linked" "none")
    "target" (slice "chrome115" "edge115" "firefox116" "ios16.4" "opera101" "safari16.4")
    "targetPath" "css/styles.css"
  }}
  {{ with . | css.Build $opts }}
    {{ if hugo.IsDevelopment }}
      <link rel="stylesheet" href="{{ .RelPermalink }}">
    {{ else }}
      {{ with . | fingerprint }}
        <link rel="stylesheet" href="{{ .RelPermalink }}" integrity="{{ .Data.Integrity }}" crossorigin="anonymous">
      {{ end }}
    {{ end }}
  {{ end }}
{{ end }}

使用上述选项时,Hugo 会做以下事情:

  • 把 PNG 与 SVG 图片以内嵌数据 URL 的形式写入生成的 CSS 代码
  • 在生产环境压缩输出,在开发环境不压缩
  • 在开发环境生成外部 source map,在生产环境不生成
  • 转换语法以兼容目标浏览器版本
  • 添加厂商前缀以兼容目标浏览器版本
  • 把生成的 CSS 代码发布到 css/styles.css
  • 在生产环境加入 SRI 哈希,并把文件哈希插入文件名

构建产物

(0.165.0 新增)

除主输出之外,Hugo 还可能作为构建的一部分发布其他文件:

  • 由 file 加载器复制到输出目录的文件,例如字体与图片
  • sourceMap 选项取 external 或 linked 时生成的 source map

返回资源上的 Data 方法把这些文件以产物切片的形式暴露出来,每一项都提供 MediaType、Permalink 与 RelPermalink 方法。

例如,为构建过程发布的字体文件渲染预加载链接:

layouts/_partials/css.htmlgo-html-template
{{ with resources.Get "css/main.css" }}
  {{ with . | css.Build }}
    {{ range .Data.Artifacts }}
      {{ if eq .MediaType.MainType "font" }}
        <link rel="preload" href="{{ .RelPermalink }}" as="font" type="{{ .MediaType.Type }}" crossorigin>
      {{ end }}
    {{ end }}
    <link rel="stylesheet" href="{{ .RelPermalink }}">
  {{ end }}
{{ end }}

常见写法

下面的例子涵盖在项目内或 Node 包内引用资源时最常见的用法。这些写法对 @import 语句以及用于图片和字体的 url() 函数记法都适用。

凡是通过路径引用的资源,包括图片、字体与样式表,都必须位于统一文件系统的 assets 目录中,或位于某个 Node 包内。

assets 目录中的文件

要引入 assets 目录中的样式表,可以使用裸路径、相对路径或根相对路径。使用裸路径时,Hugo 先相对于当前样式表查找,再相对于 assets 目录查找。

/assets/css/main.csscss
/* A bare path */
@import "variables.css";

/* A relative path */
@import "./theme.css";
@import "../layout.css";

/* A root-relative path */
@import "/css/grid.css";

/* A url() reference using the same resolution logic */
.logo { background: url("/images/logo.svg"); }

Node 包

按名称引用某个 Node 包时,Hugo 会查阅该包内的 package.json 文件来寻找入口点。

/assets/css/main.csscss
@import "bootstrap";

包内的文件

要引用某个 Node 包内的具体文件,请给出以包名开头的路径。

/assets/css/main.csscss
@import "bootstrap/dist/css/bootstrap-grid.css";

完整示例:把三个 CSS 文件合并成一个

目录与文件(同上游示例):

tree
assets/
└── css/
    ├── components/
    │   ├── a.css
    │   └── b.css
    └── main.css
assets/css/main.csscss
@import url('https://cdn.jsdelivr.net/npm/the-new-css-reset/css/reset.min.css');

@import './components/a.css';
@import './components/b.css';

.c {color: blue; }
assets/css/components/a.csscss
.a { color: red; }
assets/css/components/b.csscss
.b { color: green; }
layouts/_partials/css.htmlgo-html-template
{{ with resources.Get "css/main.css" | css.Build }}
  <link rel="stylesheet" href="{{ .RelPermalink }}">
{{ end }}

在本机(Hugo 0.167.0 extended,Windows)实测:.RelPermalink 为 /css/main.css,产物 public/css/main.css 为(注释里的绝对路径随机器变化,这里省略为 …):

css
@import "https://cdn.jsdelivr.net/npm/the-new-css-reset/css/reset.min.css";

/* ns-hugo-imp:…/assets/css/components/a.css */
.a {
  color: red;
}

/* ns-hugo-imp:…/assets/css/components/b.css */
.b {
  color: green;
}

/* <stdin> */
.c {
  color: blue;
}

你应当看到什么:两个本地 @import 被就地展开(顺序保持),而外部 URL 的 @import 原样保留——这是 esbuild 的行为;/* ns-hugo-imp:… */ 与 /* <stdin> */ 是它添加的来源注释,未压缩时会出现(实测),压缩后消失。

加上 minify 选项:

go-html-template
{{ with resources.Get "css/main.css" | css.Build (dict "minify" true) }}{{ .Content }}{{ end }}

实测 .Content 的原始值(一行,无注释):

css
@import"https://cdn.jsdelivr.net/npm/the-new-css-reset/css/reset.min.css";.a{color:red}.b{color:green}.c{color:#00f}

再用 vars 注入值,样式表里写 @import 'hugo:vars';:

go-html-template
{{ $vars := dict "ol-li-after" ("6" | css.Quoted) "font-family" "Arial" }}
{{ with resources.Get "css/vars.css" | css.Build (dict "vars" $vars) }}{{ .Content }}{{ end }}

实测 .Content 的原始值:

css
/* ns-hugo-vars:hugo:vars */
:root {
  --font-family: Arial;
  --ol-li-after: "6";
}

/* <stdin> */
.el {
  content: var(--ol-li-after);
  font-family: var(--font-family);
}

你应当看到什么:vars 会被展开成 :root 里的自定义属性;其中 ("6" | css.Quoted) 带上了引号,而 "Arial" 没有——引号由 css.Quoted 控制。设置 "targetPath" "css/styles.css" 后,实测 .RelPermalink 变为 /css/styles.css。

返回值边界(实测)

测量条件:Hugo 0.167.0 extended,Windows,最小站点。未压缩输出中的 ns-hugo-imp 注释含本机绝对路径,已省略。

情况 结果 是否报错
正常构建 返回资源;未设 targetPath 时 .RelPermalink 为 /css/main.css(原路径,扩展名改为 .css) 否
"minify" true 内容被压缩(color: blue 变为 color:#00f) 否
"targetPath" "css/styles.css" .RelPermalink 为 /css/styles.css 否
直传字符串 {{ "body{}" | css.Build }} —— 是:error calling Build: type string not supported in Resource transformations
直传 nil(resources.Get 未命中且没加 with 守卫) —— 是:error calling Build: type <nil> not supported in Resource transformations
不给资源 {{ css.Build }} —— 是:error calling Build: no Resource provided in transformation
文件不存在但用 with 守卫 整段不渲染,构建继续 否
选项名拼错 上游未说明;本站未逐项实测 ——

常见坑

类别 症状 真因 怎么修
报错看不懂 type <nil> not supported in Resource transformations resources.Get 没找到文件,返回 nil 后仍直接送进 css.Build 用 {{ with resources.Get "css/main.css" }}…{{ end }} 守卫,或先核对路径大小写
没报错但结果不对 产物里少了几段样式 被内联的 @import 路径不在 assets 目录下(或写成了绝对 URL,会被保留而不内联) 路径改为相对/裸路径,文件放进 assets;必要时用 externals 选项控制
没报错但结果不对 线上 CSS 里出现奇怪的 ns-hugo-imp 注释 没有开启 minify,esbuild 保留了来源注释 需要干净产物时开 "minify" true 或用 minify 函数再处理一次
没报错但结果不对 vars 的值带上了不该有的引号 类型推断与预期不符 用 css.Quoted、css.Unquoted 显式指定

更多排查入口见故障排查。