From 7f8ea9d6ee59a705f125a08168047a5040751d85 Mon Sep 17 00:00:00 2001
From: eltrac <hi@eltr.ac>
Date: Sun, 15 Feb 2026 13:22:13 +0800
Subject: docs: new note

---
 content/notes/hugo-not-building-scss.md | 77 +++++++++++++++++++++++++++++++++
 1 file changed, 77 insertions(+)
 create mode 100644 content/notes/hugo-not-building-scss.md

(limited to 'content')

diff --git a/content/notes/hugo-not-building-scss.md b/content/notes/hugo-not-building-scss.md
new file mode 100644
index 0000000..1f099aa
--- /dev/null
+++ b/content/notes/hugo-not-building-scss.md
@@ -0,0 +1,77 @@
++++
+title = "Hugo 推送到生产环境不构建 SCSS 的问题"
+date = 2026-02-15 13:22:02
+tags = ['Hugo','运维']
++++
+
+为了给博客添加[主题切换按钮](https://src.eltr.ac/eltrac/geedeapro/commit/52758459a220fde27f1519d3fd3e99f3f2a52f80)，将原先通过媒体查询（`@media` query）实现的暗色模式切换到了用 CSS 类名（`.dark`）实现，在本地测试无误，但合并到 `master` 分支并在 VPS 上构建之后，却出现了问题——当系统配色方案是「暗色」时，就算主动将站内的主题切换为「亮色」，也仍然会保持暗色背景；反之，在系统亮色方案下，将站内主题切换为「暗色」，却没有这个问题。
+
+排查后发现，在本地构建的 Hugo 网站没有这个问题，但是在 VPS 上构建的网站，仍然使用了老旧的 `@media` 媒体查询方案，即便源代码都是一样的，构建结果却有所不同。
+
+在后续的开发中，发现了类似的问题：修改了 SCSS 文件，本地测试没有问题，但推送到生产环境后，在 VPS 上构建的网站却没有使用最新的 SCSS，仍然使用过时的样式。
+
+## Hugo 的构建缓存？
+
+Hugo 的确会缓存资源文件，见[文档](https://gohugo.io/configuration/caches/)。不过，一般来说只会在构建过程中缓存，避免在同一个构建过程中反复从磁盘中读取相同的文件；也会在多次构建之间缓存，但照例来说不会持续好几天都只能读取到旧文件。
+
+以下是 Hugo 默认的缓存配置。
+
+```toml
+[caches]
+  [caches.assets]
+    dir = ':resourceDir/_gen'
+    maxAge = -1
+  [caches.getresource]
+    dir = ':cacheDir/:project'
+    maxAge = -1
+  [caches.images]
+    dir = ':resourceDir/_gen'
+    maxAge = -1
+  [caches.misc]
+    dir = ':cacheDir/:project'
+    maxAge = -1
+  [caches.modulequeries]
+    dir = ':cacheDir/modules'
+    maxAge = '24h'
+  [caches.modules]
+    dir = ':cacheDir/modules'
+    maxAge = -1
+```
+
+可见，除了模块查询（`module queries`）默认缓存一天之外，包括静态资源在内的其他内容都是默认没有缓存的（即值为 `-1`）。
+
+那么就不会是构建缓存的问题了。也不可能是 Cloudflare 的网络层缓存，因为网站使用的是行内 CSS，是以 `<style>` 标签嵌入到 HTML 文件里的，不会被缓存。
+
+## 尝试在 VPS 上手动构建
+
+SSH 到 VPS 上，进入博客项目的根目录，直接运行 `hugo`，发现没有任何报错。
+
+运行 `hugo --ignoreCache`，发现如下报错：
+
+```shell
+eltrac@vps:~/geedeapro$ hugo --ignoreCache
+Start building sites …
+hugo v0.156.0-DEV-24eb84f8681bc86a40c2b737969fb9b8292f26b7 linux/amd64 BuildDate=2026-02-06T14:06:19Z
+
+Total in 303 ms
+ERROR error building site: render: [zh v1.0.0 guest] failed to render pages: render of "/" failed: "/home/eltrac/geedeapro/layouts/baseof.html:3:3": execute of template failed: template: home.html:3:3: executing "home.html" at <partial "head.html" .>: error calling partial: "/home/eltrac/geedeapro/layouts/_partials/head.html:8:5": execute of template failed: template: _partials/head.html:8:5: executing "_partials/head.html" at <partial "head/css" .>: error calling partial: "/home/eltrac/geedeapro/layouts/_partials/head/css.html:20:10": execute of template failed: template: _partials/head/css.html:20:10: executing "_partials/head/css.html" at <.Content>: error calling Content: TOCSS: failed to transform "/css/main.scss" (text/x-scss). Check your Hugo installation; you need the extended version to build SCSS/SASS with transpiler set to 'libsass'.: this feature is not available in your current Hugo version, see https://goo.gl/YMrWcn for more information
+```
+
+重点在这一段：
+
+```
+you need the extended version to build SCSS/SASS with transpiler set to 'libsass'.: this feature is not available in your current Hugo version
+```
+
+这里说必须要用拓展版 Hugo 才能构建 SCSS 文件。所以之前并不是 Hugo 故意缓存，而是因为没有解析 SCSS 文件的能力，所以不得不使用旧的数据（我记得我在 VPS 上重新安装过一次 Hugo，当是可能意外安装了没有拓展的版本）。
+
+我是直接从源代码构建 Hugo 的，在构建时加上 `extended` 标签即可：
+
+```shell
+CGO_ENABLED=1 go build -tags extended .
+```
+
+*不过，如果不是为了用最新版本还是不建议自己编译，因为 VPS 的 CPU 实在是太烂了，编译要好几分钟，而且 CPU 占用率一直居高不下，太可怕了……*
+
+使用拓展后的 Hugo 重新编译网站，发现问题解决。
+
-- 
cgit v1.2.3