css.Sass
返回把给定 Sass 资源转译为 CSS 后生成的资源。
用 Hugo extended 与 extended/deploy 版本内置的 LibSass 转译器把 Sass 转译为 CSS,或者安装 Dart Sass 以使用 Sass 语言的最新特性。
Sass 有两种语法形式:SCSS 与缩进语法。Hugo 两者都支持。
这一页解决什么问题
浏览器只认 CSS——写 .scss/.sass 就必须先把它编译掉。css.Sass 就是这条编译管道:把 assets/ 下的 Sass 资源转译为 CSS 资源,再照常接进 <link>、或继续 fingerprint。Hugo 的 extended / extended-deploy 版本内置 LibSass(也是默认的 transpiler),安装 Dart Sass 后可以改用 Sass 语言的最新特性。
什么时候用,什么时候别用
该用:
- 项目本身就用 SCSS/Sass(变量、嵌套、mixin、
@use); - 想用
vars选项把站点配置注入成 Sass 变量(配合@import 'hugo:vars'或@use 'hugo:vars')。
别用:
- 处理的是纯 CSS、只做合并/压缩/补前缀 → 用
css.Build; - Tailwind CSS v4 → 用
css.TailwindCSS; - 需要 PostCSS 插件 → 用
css.PostCSS。
选项
css.Sass 函数接受一个选项映射。
enableSourceMap- (
bool) 是否生成 source map。默认是false。go-html-template{{ $opts := dict "transpiler" "dartsass" "enableSourceMap" true }} {{ $r := resources.Get "sass/main.scss" | css.Sass $opts }} importContext- (0.165.0 新增)
- (
resource.ResourceGetter) 解析@use与@import语句时使用的资源获取器。Hugo 先按语句中书写的路径在这个上下文中查找,找不到再回退到文件系统。适用于 Dart Sass。 includePaths- (
slice) 路径切片,相对于项目根目录;转译器在解析@use与@import语句时会使用这些路径。go-html-template{{ $opts := dict "transpiler" "dartsass" "includePaths" (slice "node_modules/bootstrap/scss") }} {{ $r := resources.Get "sass/main.scss" | css.Sass $opts }} outputStyle- (
string) 生成 CSS 的输出风格。使用 LibSass 时取nested(默认)、expanded、compact、compressed之一;使用 Dart Sass 时取expanded(默认)或compressed。go-html-template{{ $opts := dict "transpiler" "dartsass" "outputStyle" "compressed" }} {{ $r := resources.Get "sass/main.scss" | css.Sass $opts }} precision- (
int) 浮点运算的精度。适用于 LibSass。默认是8。go-html-template{{ $opts := dict "transpiler" "dartsass" "precision" 10 }} {{ $r := resources.Get "sass/main.scss" | css.Sass $opts }} silenceDeprecations- (0.139.0 新增)
- (
slice) 要静默的弃用项 ID 切片。ID 在 Dart Sass 的警告信息中写在方括号内(例如WARN Dart Sass: DEPRECATED [import]中的import)。适用于 Dart Sass。go-html-template{{ $opts := dict "transpiler" "dartsass" "silenceDeprecations" (slice "import") }} {{ $r := resources.Get "sass/main.scss" | css.Sass $opts }} silenceDependencyDeprecations- (0.146.0 新增)
- (
bool) 是否静默来自依赖的弃用警告。这里把通过加载路径被间接导入的任何文件都视为依赖。这不适用于@warn或@debug规则。默认是false。go-html-template{{ $opts := dict "transpiler" "dartsass" "silenceDependencyDeprecations" true }} {{ $r := resources.Get "sass/main.scss" | css.Sass $opts }} sourceMapIncludeSources- (
bool) 是否把源码嵌入生成的 source map。适用于 Dart Sass。默认是false。go-html-template{{ $opts := dict "transpiler" "dartsass" "enableSourceMap" true "sourceMapIncludeSources" true }} {{ $r := resources.Get "sass/main.scss" | css.Sass $opts }} targetPath- (
string) 资源的目标路径,相对于publishDir。不设置时,目标路径默认为该资源原路径并把扩展名改为.css。go-html-template{{ $opts := dict "transpiler" "dartsass" "targetPath" "css/bundle.css" }} {{ $r := resources.Get "sass/main.scss" | css.Sass $opts }} transpiler- (
string) 要使用的转译器,取libsass或dartsass。Hugo 的 extended 与 extended/deploy 版本包含 LibSass 转译器。要使用 Dart Sass 转译器,参见安装说明。默认是libsass。go-html-template{{ $opts := dict "transpiler" "dartsass" }} {{ $r := resources.Get "sass/main.scss" | css.Sass $opts }} vars- (
map) 用于生成 Sass 变量的键值对映射。当css.Sass函数在@use或@import语句中遇到hugo:vars这个内部标识符时,会把这些变量注入样式表。go-html-template{{ $vars := dict "font-family" "\"Times New Roman\", Times, serif" "font-size" "24px" "primary-color" "blue" }} {{ $opts := dict "transpiler" "dartsass" "vars" $vars }} {{ $r := resources.Get "sass/main.scss" | css.Sass $opts }}在上例中,只要在样式表里使用该标识符,就能以
hugo:vars命名空间下的 Sass 变量访问这些值:scss@use 'hugo:vars' as v; .element { color: v.$primary-color; font-family: v.$font-family; font-size: v.$font-size; }上面的写法会生成等价于下述内容的输出:
css.element { color: blue; font-family: "Times New Roman", Times, serif; font-size: 24px; }(0.161.0 新增)
该映射可选地包含嵌套映射。每个嵌套映射会作为一个独立的
hugo:vars/<name>命名空间暴露出来,其中<name>是嵌套映射的键(转为小写)。顶层的标量值与嵌套映射彼此独立:顶层的@use 'hugo:vars'只包含标量值,而@use '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 "transpiler" "dartsass" "vars" $vars }} {{ $r := resources.Get "sass/main.scss" | css.Sass $opts }}在样式表中,用各自独立的
@use语句引用每个嵌套命名空间。给它指定一个别名,以便访问该命名空间中的变量:scss@use 'hugo:vars' as v; @use 'hugo:vars/mobile' as mobile; body { color: v.$primary-color; font-family: v.$font-family; font-size: v.$font-size; } @media (max-width: 650px) { body { color: mobile.$primary-color; font-size: mobile.$font-size; } }上面的写法会生成等价于下述内容的输出:
cssbody { color: blue; font-family: "Times New Roman", Times, serif; font-size: 24px; } @media (max-width: 650px) { body { color: red; font-size: 12px; } }在项目配置中设置 Sass 变量时,
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 "transpiler" "dartsass" "vars" site.Params.theme.style }} {{ $r := resources.Get "sass/main.scss" | css.Sass $opts }}向
css.Sass函数传入vars映射时,Hugo 会用正则匹配识别诸如24px或#FF0000这类常见的有类型 CSS 值。必要时可以用css.Quoted或css.Unquoted函数绕过自动类型推断,明确表示某个值的类型。
示例
{{ with resources.Get "sass/main.scss" }}
{{ $opts := dict
"enableSourceMap" hugo.IsDevelopment
"outputStyle" (cond hugo.IsDevelopment "expanded" "compressed")
"targetPath" "css/main.css"
"transpiler" "dartsass"
"vars" site.Params.styles
"includePaths" (slice "node_modules/bootstrap/scss")
}}
{{ with . | css.Sass $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 }}Dart Sass
Hugo 的 extended 与 extended/deploy 版本包含 LibSass,用于把 Sass 转译为 CSS。2020 年,Sass 团队弃用 LibSass,转而推荐 Dart Sass。
在开发与生产环境中安装 Dart Sass,即可使用 Sass 语言的最新特性。
安装概览
Dart Sass 与 Hugo v0.114.0 及更高版本兼容。
如果你曾在 Hugo v0.113.0 及更早版本中使用 Embedded Dart Sass1,请先卸载 Embedded Dart Sass,再安装 Dart Sass。若两者都已安装,Hugo 会使用 Dart Sass。
如果你是通过 Snap 包安装 Hugo 的,则无需再安装 Dart Sass,Hugo 的 Snap 包已包含 Dart Sass。
开发环境
只要把 Dart Sass 安装到 PATH 中的某个位置,Hugo 就能找到它。
| 操作系统 | 包管理器 | 站点 | 安装方式 |
|---|---|---|---|
| Linux | Homebrew | brew.sh | brew install sass/sass/sass |
| Linux | Snap | snapcraft.io | sudo snap install dart-sass |
| macOS | Homebrew | brew.sh | brew install sass/sass/sass |
| Windows | Chocolatey | chocolatey.org | choco install sass |
| Windows | Scoop | scoop.sh | scoop install sass |
你也可以为 Linux、macOS 与 Windows 安装预编译二进制文件。预编译二进制文件必须安装在项目目录之外,并确保其路径包含在系统的 PATH 环境变量中。
运行 hugo env 可以列出当前生效的转译器。
生产环境
要在 CI/CD 平台上把 Dart Sass 与 Hugo 一起使用,通常必须修改构建工作流,在 Hugo 站点构建开始之前安装 Dart Sass。因为这类平台没有预装 Dart Sass,而 Hugo 需要它来处理 Sass 文件。
有一个重要的例外可以跳过这一步:你已经把 resources 目录提交到了仓库。这只有在下列条件都满足时才可行:
- 你没有改动 Hugo 默认的资源缓存位置。
- 你没有在项目配置中把
useResourceCacheWhen设为 never。
把 resources 目录提交上去,就等于把预构建好的 CSS 文件直接交给 CI/CD 平台,平台因此无需自己运行 Sass 编译。
关于如何在生产环境中安装 Dart Sass 的示例,参见下列托管指南:
完整示例:编译一个 SCSS 文件
{{ with resources.Get "sass/main.scss" | css.Sass }}
<link rel="stylesheet" href="{{ .RelPermalink }}">
{{ end }}$color: #333;
body { color: $color; }在本机(Hugo 0.167.0 extended,Windows,未安装 Dart Sass,走默认的 LibSass)实测:.RelPermalink 为 /sass/main.css,产物 public/sass/main.css 为:
body {
color: #333; }你应当看到什么:变量 $color 被替换成 #333。默认 outputStyle 是 LibSass 的 nested,所以花括号收在最后一条声明那一行——这是实测结果,不是排印错误。换 "outputStyle" "expanded" 会得到逐行展开的常规格式,换 "compressed" 得到压缩结果 body{color:#333}(均实测)。
用 vars 注入值(LibSass 路径写 @import 'hugo:vars';):
{{ $vars := dict "ol-li-after" ("6" | css.Quoted) }}
{{ $opts := dict "vars" $vars "outputStyle" "expanded" }}
{{ with resources.Get "sass/main.scss" | css.Sass $opts }}{{ .RelPermalink }}{{ end }}@import 'hugo:vars';
body {
content: $ol-li-after;
}实测产物:
body {
content: "6";
}你应当看到什么:变量命名空间里的 $ol-li-after 可用,值带引号(由 css.Quoted 决定)。设置 "targetPath" "css/my.css" 后,实测 .RelPermalink 变为 /css/my.css。
返回值边界(实测)
测量条件:Hugo 0.167.0 extended(内置 LibSass,未安装 Dart Sass),Windows,最小站点。
| 情况 | 结果 | 是否报错 |
|---|---|---|
| 默认编译 | 资源;.RelPermalink 为 /sass/main.css;outputStyle 为 nested |
否 |
"outputStyle" "expanded" |
逐行展开 | 否 |
"outputStyle" "compressed" |
body{color:#333} |
否 |
"targetPath" "css/my.css" |
.RelPermalink 为 /css/my.css |
否 |
"transpiler" "dartsass"(未安装 Dart Sass) |
—— | 是:TOCSS-DART: failed to transform "/sass/main.scss" (text/x-scss). You need to install Dart Sass, see https://gohugo.io//functions/css/sass/#dart-sass: this feature is not available in your current Hugo version |
SCSS 语法错误(body { color: ; }) |
—— | 是:TOCSS: failed to transform "/sass/bad.scss" (text/x-scss): "…bad.scss:1:13": style declaration must contain a value |
LibSass 下用 @use "hugo:vars" as h; |
—— | 是:TOCSS: …: Invalid CSS after "body { content: h": expected expression (e.g. 1px, bold), was ".$ol-li-after; }" |
LibSass 下直接写 $var 但没引入 hugo:vars |
—— | 是:TOCSS: …: Undefined variable: "$ol-li-after" |
直传字符串 {{ "body{}" | css.Sass }} |
—— | 是:error calling Sass: type string not supported in Resource transformations |
直传 nil |
—— | 是:error calling Sass: type <nil> not supported in Resource transformations |
文件不存在但用 with 守卫 |
整段不渲染 | 否 |
常见坑
| 类别 | 症状 | 真因 | 怎么修 |
|---|---|---|---|
| 报错看不懂 | TOCSS-DART: … You need to install Dart Sass |
设置了 "transpiler" "dartsass" 但系统 PATH 里没有 Dart Sass |
安装 Dart Sass(choco install sass / scoop install sass / Homebrew),或去掉该选项改用内置 LibSass |
| 报错看不懂 | Invalid CSS after "body { content: h": expected expression … |
在 LibSass 下用了 Dart Sass 的 @use 语法 |
LibSass 用 @import 'hugo:vars';,Dart Sass 才用 @use 'hugo:vars' as h; |
| 报错看不懂 | Undefined variable: "$xxx" |
样式表里没引入 hugo:vars 命名空间 |
在文件顶部加 @import 'hugo:vars';(或 Dart Sass 的 @use) |
| 没报错但结果不对 | 改了 .scss 但产物没变 |
资源缓存 | 构建时加 --ignoreCache,或清理 resources/_gen |
| 没报错但结果不对 | 产物格式与预期不符(花括号挤在最后一行) | LibSass 的 nested 是默认输出格式 |
显式设置 "outputStyle" "expanded" 或 "compressed" |
更多排查入口见故障排查。
-
2023 年,Sass 团队弃用 Embedded Dart Sass,转而推荐 Dart Sass。 ↩︎