fix(build): next build never reuses Turbopack's persistent cache, which served the previous globals.css (BUG-2136)

Next 16.3.1 turns on turbopackFileSystemCacheForBuild by default and keeps it in
.next/cache/turbopack, inside the image build's BuildKit cache mount. Reproduced
locally: a cold build at e8e358213, then a build at 0bf3210c8 reusing only
.next/cache, lost the four .birth-place-coordinate* classes exactly as CI did.
With the cache off the same rebuild carries every class; Turbopack compile time
is 21.0 s either way. Recurrence of BUG-2069, whose cache-id rename only reset
the cache once.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01DbBXoyn7Hj3LCW3BUs5bZ8
This commit is contained in:
2026-11-21 23:59:55 +08:00
co-authored by Claude Opus 5.5
parent 0bf3210c8d
commit c02b1fc46b
5 changed files with 46 additions and 1 deletions
+1 -1
View File
@@ -186,7 +186,7 @@ The gate's validation runs as two jobs at once on the `xiaoxin` runner: `validat
| `jyotisha-pip` | pip download cache | kept |
| `jyotisha-npm` | npm download cache mounted into the `npm ci` container | kept |
The web image build also uses BuildKit cache mounts (`jyotisha-web-npm`, `jyotisha-web-next-v2`); they live in the BuildKit store and are pruned by `deploy/reclaim-runner-disk.sh` only when the runner is short on disk. Deleting any of these only makes the next run slower. Right after `next build` the image build runs `frontend/scripts/check-built-css.mjs`: if a class from `globals.css` is missing from the built style sheets (the Next cache served an old sheet, BUG-2069) the build fails; change the version suffix of the `jyotisha-web-next-v2` cache id to start from an empty cache.
The web image build also uses BuildKit cache mounts (`jyotisha-web-npm`, `jyotisha-web-next-v2`); they live in the BuildKit store and are pruned by `deploy/reclaim-runner-disk.sh` only when the runner is short on disk. Deleting any of these only makes the next run slower. Right after `next build` the image build runs `frontend/scripts/check-built-css.mjs`: if a class from `globals.css` is missing from the built style sheets (the Next cache served an old sheet, BUG-2069) the build fails. The old sheet came from Turbopack's persistent build cache (`.next/cache/turbopack`, on by default in Next 16); `frontend/next.config.ts` sets `experimental.turbopackFileSystemCacheForBuild: false`, so a warm build no longer reuses compiled CSS (BUG-2136, reproduced and verified locally; Turbopack compile time was 21.0 s with and without it). If the check still fires, the cause is elsewhere: renaming the cache id only resets it once.
Every Web image build must pass that same full 40-character commit as the Docker
build argument `NEXT_DEPLOYMENT_ID`. Next.js embeds it during `next build`, adds
+4
View File
@@ -36,6 +36,10 @@ COPY skills /app/skills
# speeds up compilation and never lands in the image.
# The cache id carries a version: BUG-2069 shipped the previous build's
# globals.css out of the old cache, so that cache is left behind.
# BUG-2136: the stale CSS came from Turbopack's persistent build cache
# (.next/cache/turbopack), which Next 16 turns on by default; next.config.ts
# now sets turbopackFileSystemCacheForBuild: false, so this mount no longer
# feeds compiled CSS into a build. Renaming the id (BUG-2069) only reset it once.
RUN --mount=type=cache,id=jyotisha-web-next-v2,target=/app/frontend/.next/cache npm run build
# A build that reused old CSS fails here instead of reaching a server.
RUN node scripts/check-built-css.mjs
+13
View File
@@ -28853,3 +28853,16 @@
- 尚未处理:服务端只校验范围,不校验 500 公里;后台重置账户时清空经纬度但不改来源标记(没有坐标时标记不起作用);星盘页没有单独的时区行。
- 关联记录:BUG-1506、BUG-2051、BUG-2067,占星师 2026-11-20 第 13 问。
- 修复版本:`claude/birth-coordinates-2125`。
## BUG-2136 | 测试环境镜像又带上了旧的全站样式:Turbopack 的持久构建缓存复用了上一次编译的 globals.css
- 状态:fixed-pending-verify(本机复现并验证修复;要等下一次测试环境构建确认)。
- 首次发现 / 最近更新:2026-11-21 / 2026-11-21。
- 现象:问答可读性窗口的 `0bf3210c8`(BUG-2125,给 globals.css 加了 4 个 `.birth-place-coordinate*` 类)通过了两项测试,但镜像构建在 `check-built-css` 失败:构建出的样式表里没有这 4 个类。不带缓存的干净构建里 4 个类都在。
- 关联记录:**BUG-2069 的复发**。BUG-2069(2026-11-20,`e4b25c26`)同样是镜像带了上一版的 globals.css。当时只把 BuildKit 缓存名换成 `jyotisha-web-next-v2`,并加了 `check-built-css` 守卫;换缓存名只能把缓存清空一次,下一次照样会被旧内容填上,所以这次又出现了。守卫本身起了作用:这次是在镜像构建时拦下,没有部署到测试环境。
- 根因(本机复现确认):`next build` 在 Next 16.3.1 默认用 Turbopack(构建日志第一行 `Next.js 16.3.1 (Turbopack)`),并且默认打开 Turbopack 的持久构建缓存(`node_modules/next/dist/server/config-shared.js`:`turbopackFileSystemCacheForBuild: true`),缓存放在 `.next/cache/turbopack`,正好在镜像构建的 BuildKit 缓存挂载里。复现:在 `e8e358213` 冷构建一次(1 分 54 秒,检查通过)→ 切到 `0bf3210c8`、只保留 `.next/cache`、再构建 → 缺同样的 4 个类,和 CI 一模一样。只改一个样式文件的最小工程复现不出来,所以和项目规模或依赖关系有关,具体是 Turbopack 哪一层没有失效没有继续追。
- 修复:`frontend/next.config.ts` 在 `experimental` 里设 `turbopackFileSystemCacheForBuild: false`,构建不再读写 Turbopack 持久缓存。用同一份旧缓存再构建:4 个类都在,检查通过。Turbopack 编译时间开和关都是 21.0 秒(冷构建 28.6 秒),构建总时间主要花在类型检查和页面生成,不受影响。`deploy/railway-web.Dockerfile` 和 `deploy/README.md` 写明原因;BuildKit 缓存挂载和 `check-built-css` 守卫保留。
- 验证:本机三次真实构建(见上);`frontend/tests/turbopack-build-cache-2136.test.ts`(配置里关着、镜像仍有守卫并写明原因);`frontend/tests/built-css-check-2069.test.ts`、`staging-backend-workflows`(只剩本机固有的 yaml / rsync 失败)、`tests/test_railway_deployment.py` 通过。
- 防复发:测试钉住这个开关;`check-built-css` 继续在镜像构建里拦截。
- 修复版本:`claude/css-cache-2136`。
+6
View File
@@ -26,6 +26,12 @@ const nextConfig: NextConfig = {
devIndicators: false,
experimental: {
authInterrupts: true,
// BUG-2136: Next 16 keeps a persistent Turbopack cache for `next build` by default
// (.next/cache/turbopack). The image build mounts .next/cache across builds, and a warm
// build reused the previous compiled globals.css after its rules changed (BUG-2069 on
// e4b25c26, again on 0bf3210c8; reproduced locally: e8e358213 → 0bf3210c8 lost the four
// .birth-place-coordinate* classes). Compile time is the same without it (21.0 s both ways).
turbopackFileSystemCacheForBuild: false,
optimizePackageImports: [
"@ant-design/icons",
"@refinedev/antd",
@@ -0,0 +1,22 @@
/**
* BUG-2136: a warm `next build` reused the previous compiled globals.css from Turbopack's
* persistent build cache (Next 16 default), twice shipping or nearly shipping old styles
* (BUG-2069 on e4b25c26; 0bf3210c8 caught by check-built-css). The build cache stays off;
* the image keeps the CSS guard and the documented reason.
*/
import assert from "node:assert/strict";
import { readFileSync } from "node:fs";
import test from "node:test";
const read = (path: string) => readFileSync(new URL(path, import.meta.url), "utf8");
test("next build never reuses Turbopack's persistent cache", () => {
assert.match(read("../next.config.ts"), /experimental:\s*\{[\s\S]*turbopackFileSystemCacheForBuild:\s*false,/);
});
test("the image still checks the built CSS and says why the Turbopack cache is off", () => {
const dockerfile = read("../../deploy/railway-web.Dockerfile");
assert.match(dockerfile, /npm run build\n# [^\n]+\nRUN node scripts\/check-built-css\.mjs\n/);
assert.match(dockerfile, /BUG-2136[\s\S]*turbopackFileSystemCacheForBuild: false/);
assert.match(read("../../deploy/README.md"), /turbopackFileSystemCacheForBuild: false/);
});