docs: close the open reactCompiler keep-or-roll-back decision

Decision is to stay rolled back: the round's target was Home, and the
44 functions the compiler does optimize have no measured render benefit
to justify the +2.50% first-load JS. Reopening this should start by
benchmarking those 44, not by flipping the config.

Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
Jesse_Chen
2026-08-17 15:44:36 +08:00
parent 1831befc68
commit f78ad09fcc
2 changed files with 5 additions and 1 deletions
+1 -1
View File
@@ -8,7 +8,7 @@
- **`Home` 的编译失败原因无法定位,需要授权新增依赖。** Next 16.3.1 的 Rust 版 React Compiler 拒编 `page.tsx``Home`(2730 行),且不报任何错误或警告。`panicThreshold: "all_errors"` 在 Rust 版下形同虚设(试过两次,构建既不报错也不打印诊断),因此拿不到「哪一行挡住了编译器」。唯一能出诊断的路是换 Babel 版(`experimental.turbopackRustReactCompiler: false`),但它需要新增依赖 `babel-plugin-react-compiler`next 的可选 peer,未装;Next 只内置了 compiler runtime,没内置这个 plugin),撞任务书「不新增依赖」,故未做。想继续定位需要授权装这个依赖,或等上游 Rust 版补上诊断输出。
- **`Home` 要真正受益很可能得拆组件,属业务代码重构,本轮明令禁止。** 证据是同一文件里两个小组件(原始行 760、815)被正常编译、全项目另有 44 个函数被编译,唯独这个 2730 行、24 个 `useState`、18 个 `useEffect` 的函数被拒。任务书要求「哪处代码挡住了编译器就写进 BLOCKED.md,不要自行改写」,故 `frontend/src/**` 一行业务代码未动(仅反向验证时临时加删一行 `"use no memo"`,已还原,`git diff` 为空)。
- **待决策:是否为了 `page.tsx` 之外的 44 个组件保留 `reactCompiler: true`。** 本轮按任务 2 止损条款已回滚该配置。数据是:构建耗时无可测量变化(噪声内),`/` 首屏 JS gzip +12031 B / +2.50 %,换来 44 个函数自动记忆化,其中 `app-sidebar`112 槽)、`sidebar-session-row`73 槽)、`birth-date-picker`(58 槽)与三个引导 hook 都在 `/` 上渲染。这 44 个的实际运行时收益本轮未测量(无渲染基准),所以不替决策者拍板。重新开启只需在 `frontend/next.config.ts` 顶层加 `reactCompiler: true``experimental` 里加 `turbopackRustReactCompiler: true`
- **~~待决策~~ 已决策(2026-08-17):维持回滚,不为那 44 个组件保留 `reactCompiler: true`;若要翻案,前置条件是先测出那 44 个的渲染基准。** 本轮按任务 2 止损条款已回滚该配置。数据是:构建耗时无可测量变化(噪声内),`/` 首屏 JS gzip +12031 B / +2.50 %,换来 44 个函数自动记忆化,其中 `app-sidebar`112 槽)、`sidebar-session-row`73 槽)、`birth-date-picker`(58 槽)与三个引导 hook 都在 `/` 上渲染。这 44 个的实际运行时收益本轮未测量(无渲染基准),所以不替决策者拍板。重新开启只需在 `frontend/next.config.ts` 顶层加 `reactCompiler: true``experimental` 里加 `turbopackRustReactCompiler: true`
- **`compilationMode: "all"` 不可用,会破坏构建。** 它会编译模块作用域的普通回调,`frontend/src/components/birth-time-intake.tsx:22``Array.from({ length: 24 }, (_, index) => ...)` 被插入 `useMemoCache`,预渲染 `/` 时抛 `TypeError: Cannot read properties of null (reading 'useMemoCache')`。这是该模式本身的性质(官方标注为不安全),不是本仓库代码的缺陷,未做任何改动。
- **顺手活一律未做,登记在此:** 其一,`frontend/src/lib/skill-package-registry.ts:523``readFileSync(currentRegistryPath, "utf8")` 触发 Turbopack 构建警告「Dynamic filesystem access causes tracing of the whole project」,会把整个项目(含 `public/`)打进 server 产物,影响部署体积;升级前后都存在,与本轮无关,未改。其二,`npx eslint` 有 4 个既有 `no-unused-vars` warning,分别在 `birth-time-candidate-result.tsx:143``birth-time-candidate-completion.ts:10,11``tests/identity-auth-factory.test.ts:48`,未改。其三,`eslint-config-next` 仍是 16.2.10、与 next 16.3.1 版本号不同步,但 eslint 实测 0 error,按「不许顺手升别的依赖」未动。
- **测试环境噪声(非阻塞,已自行消化):** `frontend/tests/rectification-v9-database.test.ts` 的「v9 migration applies on a fresh database and re-applies idempotently」在全量并发下偶发失败(`database migration failed`,1 !== 0),单独重跑 7/7 通过、全量重跑 1592/1592 通过。靠 Docker 起临时 Postgres,判定为资源争用型 flake,与 Next 版本无关。未改任何测试文件。
+4
View File
@@ -193,6 +193,10 @@ React Compiler 在所有六种配置下都拒编 `Home`,包括显式 `"use mem
而不是顺手替决策者拍板。要重新开启只需在 `frontend/next.config.ts` 加回两行,
本文件的第 1/6 次尝试记录了确切写法。
**该决策已有结论(2026-08-17,交付后确认):维持回滚。** 理由是本轮目标是 `Home`
而那 44 个组件的运行时收益没有测量数据支撑首屏 +2.50 % 的代价。
若日后要改变这个结论,前置条件应当是先给那 44 个组件测出渲染基准,而不是直接开配置。
## 收尾
`docs/BUG_HISTORY.md` 追加 `BUG-255`。按 BUG-253 的防复发要求先检索最大编号:本地基点