把 Sass 编译为 CSS
用 css.Sass 把 Sass 或 SCSS 编译为 CSS,再压缩与加指纹。含 extended 版依赖、Dart Sass 安装与常见报错。
开始之前,你需要
读完之后你能
- 把 SCSS/Sass 编译成 CSS,并发布成带哈希文件名的样式表
- 用项目配置里的颜色、字号生成 Sass 变量(
vars选项 +hugo:vars) - 在构建失败时,区分「用了非 extended 版」「Dart Sass 没装」「
@use路径没配」这三类原因
这一页解决什么问题
浏览器不认识 SCSS:变量、@use、嵌套规则它都读不懂。这一步把 .scss / .sass 编译成普通 CSS,并让产物带上哈希文件名,从而可以被浏览器长期缓存。
编译要在 Hugo 里完成,需要满足一个前提:Hugo 必须能找到一个 Sass 转译器。这一点决定了本节一半以上的报错。
适用前提
用 css.Sass 函数把 Sass 转译为 CSS。Hugo 的 extended 版与 extended/deploy 版内置了 LibSass 转译器;若想使用 Sass 语言的最新特性,则需另行安装 Dart Sass。Sass 有 SCSS 与缩进语法两种书写形式,Hugo 都支持。
转译器的选择由 transpiler 选项决定,取值为 libsass 或 dartsass,默认是 libsass。(v0.153.0 起弃用) 内置的 LibSass 转译器已标记为过时并将在未来的版本中移除,因此建议改用 Dart Sass:把 transpiler 设为 dartsass 即可。
采用 Dart Sass 时,把它装进 PATH 覆盖到的位置,Hugo 就能找到它。用 hugo env 命令可以列出当前生效的转译器。在持续集成的构建环境中,通常需要在构建开始前先安装 Dart Sass,除非你已按原样把 resources 目录提交进仓库。
为什么「extended」这件事必须提前确认
LibSass 是编译进 Hugo 可执行文件的,普通版里根本没有这段代码。所以非 extended 版遇到 css.Sass 时不会「编译出一点东西」,而是直接失败:
TOCSS: failed to transform "sass/main.scss" (text/x-sass): this feature is not available in your current Hugo version, see https://goo.gl/YMrWcn for more information.看到 this feature is not available in your current Hugo version 就是这个问题:换 extended 版,或改用 Dart Sass(后者不依赖二进制里的转译器)。
Windows 上常见的原因是装了 Hugo.Hugo 而不是 Hugo.Hugo.Extended;macOS 上是 brew install hugo 装到了非 extended 的公式。详见安装 Hugo。
取得资源
样式表同样要先作为资源取出,再进入管道。资源位于资产目录 assets 中,例如 assets/sass/main.scss 就写为 resources.Get "sass/main.scss"。
路径是相对于 assets/ 的,不要写 assets/sass/main.scss——那样 Hugo 会在 assets/assets/ 里找,结果拿到 nil,随后在管道里报一个看起来与 Sass 无关的错。
管道方法链
{{ $opts := dict "transpiler" "dartsass" }}
{{ $r := resources.Get "sass/main.scss" | css.Sass $opts }}选项以映射形式传入,要与其他函数串成管道链时紧随其后:
{{ $r := resources.Get "sass/main.scss" | css.Sass $opts | resources.Minify | resources.Fingerprint }}顺序为什么是「编译 → 压缩 → 指纹」:压缩和指纹处理的都是编译之后的 CSS。把指纹放在编译前,integrity 记录的就不是浏览器实际收到的那份内容,浏览器会拒绝加载样式表。
配置选项
css.Sass 接受一个选项映射,常用键如下。
transpiler:转译器,libsass或dartsass,默认libsass。outputStyle:输出样式。LibSass 可取nested(默认)、expanded、compact、compressed;Dart Sass 取expanded(默认)或compressed。enableSourceMap:是否生成 source map,默认false。另有sourceMapIncludeSources决定是否把源文件嵌入 source map,默认false,适用于 Dart Sass。targetPath:目标路径,相对于publishDir;若不设置,则默认为资源原路径换用.css扩展名。includePaths:一个路径切片,用于解析@use与@import,例如node_modules/bootstrap/scss。precision:浮点运算精度,默认8,适用于 LibSass。silenceDeprecations与silenceDependencyDeprecations:用于压制度弃告警,后者默认false,适用于 Dart Sass。vars:键值映射,用来生成 Sass 变量。
Sass 变量
vars 中的变量会在样式表里遇到 hugo:vars 这一内部标识符时注入。在配置文件中集中定义颜色与字号,再交给模板,是一种常见做法:
[params.theme.style]
font-family = '"Times New Roman", Times, serif'
font-size = '24px'
primary-color = 'blue'{{ $opts := dict "transpiler" "dartsass" "vars" site.Params.theme.style }}
{{ $r := resources.Get "sass/main.scss" | css.Sass $opts }}样式表中以 @use 'hugo:vars' as v; 引入后,即可用 v.$primary-color 这样的形式取值。传入 vars 时,Hugo 会用正则匹配识别 24px、#FF0000 一类常见的带类型 CSS 值;必要时可用 css.Quoted 或 css.Unquoted 明确指定类型,避免自动推断造成歧义。
完整可运行示例
下面这一套不需要任何主题,直接跑通「配置 → SCSS → 编译 → 指纹 → 页面引用」。
① 建项目并进入目录:
hugo new project sass-demo
cd sass-demo② 在项目配置 hugo.toml 末尾追加颜色与字号:
[params.theme.style]
font-family = '"Times New Roman", Times, serif'
font-size = '24px'
primary-color = 'blue'③ 新建样式表 assets/sass/main.scss:
@use 'hugo:vars' as v;
body {
color: v.$primary-color;
font-family: v.$font-family;
font-size: v.$font-size;
}④ 新建首页模板 layouts/home.html:
{{ with resources.Get "sass/main.scss" }}
{{ $opts := dict
"transpiler" "dartsass"
"outputStyle" "expanded"
"vars" site.Params.theme.style
}}
{{ with . | css.Sass $opts }}
{{ $css := . | fingerprint }}
<!doctype html>
<html lang="zh-cn">
<head>
<meta charset="utf-8">
<title>Sass 编译演示</title>
<link rel="stylesheet" href="{{ $css.RelPermalink }}" integrity="{{ $css.Data.Integrity }}" crossorigin="anonymous">
</head>
<body>
<h1>这行字的颜色与字体来自 Sass 变量</h1>
</body>
</html>
{{ end }}
{{ end }}⑤ 预览:
hugo server你应当看到什么
-
页面上的标题是蓝色、衬线字体(
Times New Roman),字号明显大于默认值——说明配置里的值真的进了 CSS; -
查看网页源代码,
<link>的href形如/sass/main.<哈希>.css:说明targetPath未设置时,Hugo 用了原路径换成.css扩展名,并附上了指纹; -
执行一次
hugo后,public/sass/main.<哈希>.css存在,打开它应当看到展开格式的 CSS:cssbody { color: blue; font-family: "Times New Roman", Times, serif; font-size: 24px; } -
把
outputStyle改成"compressed"再构建一次,同一份文件的 CSS 会挤成一行——这可以用来确认选项确实生效。
什么时候用 / 什么时候别用
该用的时候
- 你已经在写 SCSS/Sass,或者要用变量、嵌套、
@use组织多个样式文件; - 你希望把站点配置里的颜色、字号注入样式表(
vars+hugo:vars); - 你需要编译后立刻压缩并加指纹。
别用的时候
- 只有一份普通 CSS,没有变量与嵌套:直接放
static/让 Hugo 原样复制,或用resources.Get后只做minify/fingerprint,少一层工具链就少一处失败点; - 你要用的是 PostCSS 插件生态(自动前缀、Tailwind 等):走PostCSS 那条路。不要为了同一份文件同时上 Sass 与 PostCSS ——两条链各自缓存、各自输出,维护成本翻倍;
- 你只是想在 CSS 里做一点变量替换:
resources.ExecuteAsTemplate也能做,见从模板创建资源。
常见坑
① 命令找不到(命令类)
| 现象 | 原因 | 处理 |
|---|---|---|
hugo: command not found |
Hugo 没装或没进 PATH |
安装 Hugo |
构建报 this feature is not available in your current Hugo version |
用的是非 extended 版 | 换 extended 版,或改用 Dart Sass |
hugo env 里没有 Dart Sass,而 transpiler 设成了 dartsass |
Dart Sass 没装或不在 PATH |
npm install -g sass、brew install sass/sass/sass,或下载预编译二进制并加入 PATH |
② 没报错但结果不对(静默失败类)
| 现象 | 原因 | 怎么确认 |
|---|---|---|
| 页面完全没样式,构建无报错 | resources.Get 的路径写成了 assets/sass/main.scss,返回 nil,with 把整段跳过 |
改成相对 assets/ 的 sass/main.scss |
| 样式是旧的 | 编译结果的哈希没变,说明输入的 SCSS 没被读到(文件名/路径错了) | 改一个明显的值(如颜色)再构建,看文件名哈希是否变化 |
| 配置里的颜色没生效 | 配置写成了 [params.theme.style] 之外的位置,或模板里没传 vars |
临时在页面上打印 {{ site.Params.theme.style }} 检查 |
hugo server 正常,CI 上失败 |
CI 环境里没有 Dart Sass | 在构建工作流里先安装 Dart Sass,或提交 resources/ 目录 |
③ 报错看不懂(报错类)
TOCSS: failed to transform ...:TOCSS是「to CSS」这一环的通用前缀,后面的那句才是原因。先读冒号后半段,再决定是版本问题、路径问题还是语法问题;Error: Can't find stylesheet to import.一类 Dart Sass 报错:@use/@import的目标没找到。用includePaths指明搜索目录(例如node_modules/bootstrap/scss),或检查相对路径;- 报错里出现
expected ";"/expected "}"之类:SCSS 语法错误,报错文件与行号指向的就是源文件本身,直接去那一行看; - 报错指向的文件与你改的无关:渲染期问题常常这样冒出来,见故障排查。
逐级排查的顺序:hugo version 有没有 +extended → hugo env 有没有 Dart Sass → 资源路径是否相对 assets/ → SCSS 语法是否有错。
相关页面
- css.Sass(完整的选项参考与 Dart Sass 各平台安装表)
- css.Quoted / css.Unquoted(显式指定变量类型)
- PostCSS
- 资源指纹
- 故障排查