Files
ssw-platform/docs/build-bloat.md
T
admin a27389d0d0 docs: 补《编译膨胀问题及处理》—— target/ 58G 的根因、处置与规矩
新增 docs/build-bloat.md,记录 2026-11-03 这次磁盘膨胀的完整处置:

- 现象:target/ 58G(deps 45G + incremental 12G + release 820M),磁盘 87%
- 根因:cargo 默认传 -C incremental=…,而 sccache 遇 incremental 直接拒缓存
  (server 端日志 CannotCache(incremental))⇒ 8.4G 缓存全是废的,每轮从零重编
- 处置:根 Cargo.toml 加 [profile.dev] incremental = false + cargo clean
- 结果:58G → 1.2G;清空后重建 63s → 14.14s(缓存命中,命中率 86.71%);
  磁盘 87% → 75%(跑完测试后 76%)
- 定位方法论:发现 sccache 命中率异常时看 server 端日志
  (SCCACHE_LOG=debug + SCCACHE_ERROR_LOG),client 端统计只说「没命中」
- 区分表:哪些是编译中间产物(该清)、哪些不是(node_modules / pglite 数据,
  按既定约定不动)
- 沉淀 6 条规矩(清前 pgrep、用 cargo clean 而非 rm -rf、sccache 缓存不在项目内、
  改 profile 要重新体检 target 体积等)

索引同步:docs/README-project.md(链接区 + 目录树)、README.md(目录树)。

验证:check-citations 4/4、check-naming 3/0/1、check-arch 20/20、
check-boundary 12/12、check-contract 10/10、check-module 123/123 全绿。
2026-11-03 23:11:26 +08:00

8.4 KiB
Raw Blame History

编译膨胀问题及处理(ssw-platform)

一句话:2026-11-03 发现 target/ 涨到 58G(磁盘已用 87%), 根因不是「Rust 编译本来就大」,而是 增量编译让 sccache 全程空转 ⇒ 缓存形同虚设、 每轮构建都从零重编。处置 = 清空 target/ + 关掉 dev 增量编译。 结果:58G → 1.2G,且「清空后重建」从 63s 缩到 14s(走缓存命中)。


1. 现象

项 值
target/ 体积 58G(debug/deps 45G + debug/incremental 12G + release 820M)
target/ 文件数 683,476(其中 debug/deps 540,833)
磁盘占用 87%(/System/Volumes/Data,可用仅剩 59 GiB)
依赖规模 Cargo.lock 174 个包(本仓 17 个 crate + 外部依赖)
sccache 缓存实体 ~/.cache/sccache 8.4G
sccache 命中率 0(Cache hits 恒为 0,Non-cacheable calls = 请求数)

同期项目内其它占用(用来区分「什么是编译中间产物」):

路径 体积 是什么 是否该清
target/ 58G 编译中间产物 ✅ 清
src/frontend/node_modules 74M 前端依赖(非编译产物) ❌ 不清(删了下次重下,且重下更慢更占)
src/backend/data/(pglite) 60M 运行期数据 ❌ 不清(是数据不是垃圾)
.git/ 19M 版本历史 ❌ 不清
crates/ 3.2M 真源代码 ❌ 不清
scripts/__pycache__ 124K Python 字节码缓存 ✅ 清(自动重建)

2. 根因:incremental 让 sccache 拒缓存

2.1 为什么值得深挖

本机 ~/.cargo/config.toml 早就配好了 sccache:

[build]
rustc-wrapper = "/Users/xs/.cargo/bin/sccache"

[env]
SCCACHE_DIR = { value = ".cache/sccache", relative = true }

缓存实体也有 8.4G(20,409 个文件)。按常理,target/ 应该是「小而精」的—— cargo clean 之后重建走缓存命中,十几秒就回来了。

但实测 sccache --show-stats 的 Cache hits 恒为 0。

2.2 定位过程(关键:看 server 端日志,不要只看 client 端统计)

client 端统计只告诉你「没命中」,不告诉你「为什么」。开 server 端 debug 日志才看到真相:

export SCCACHE_DIR="$HOME/.cache/sccache"
export SCCACHE_LOG=debug
export SCCACHE_ERROR_LOG=/tmp/scc_err.log
sccache --stop-server; sccache --start-server
touch src/lib.rs && cargo build --offline
grep -iE 'unhandled|cannotcache' /tmp/scc_err.log

server 端日志原文:

parse_arguments: CannotCache(incremental):
  ["--crate-name", "sccprobe", "--edition=2021", "src/lib.rs", ...,
   "-C", "incremental=/private/tmp/scc-probe/target/debug/incremental", ...]

2.3 因果链

cargo 默认给 rustc 传 -C incremental=<target/debug/incremental>
        │
        ▼
sccache 遇到 incremental ⇒ 拒缓存(CannotCache(incremental))
        │
        ▼
Cache hits 恒为 0,8.4G 缓存全是废的
        │
        ▼
每轮构建都从零重编 ⇒ deps 堆到 45G、incremental 堆到 12G
        │
        ▼
target/ = 58G,磁盘 87%

关键点:增量编译与 sccache 是互斥的。开了增量,sccache 就完全不介入; 于是你既没有得到增量加速(因为缓存判据失效后每次都全量),又付出了磁盘代价—— 两头落空。

2.4 旁证:deps 里堆着 10 个历史 rlib

230.6 MB  libssw_platform-c9e02b20408f6637.rlib
230.6 MB  libssw_platform-538da23eaac2c350.rlib
215.3 MB  libssw_platform-5d60b88b38c2b355.rlib
213.6 MB  libssw_platform-c94ffde5df1ce787.rlib
168.1 MB  libssw_platform-bc6ce2ecdfc0f0fd.rlib
...(共 10 个,每个 100–230 MB)

cargo 永远不会自动清理这些历史产物——每次改 profile 参数、换 feature 组合、 换 rustc 版本,都会把整套旧产物留在盘上。这与 xstudio/scripts/reclaim-space.sh 里记的同一现象(dbx 的 target 曾到 2.4 GB,依赖图只有 556 个 crate,盘上却有 863 个 rlib) 是同一个病。


3. 处置

3.1 修根因:关掉 dev 增量编译

根 Cargo.toml 新增(注意:必须在 workspace 根,成员 crate 里写 [profile.*] cargo 会报错):

[profile.dev]
incremental = false

为什么这行有效:

  • 去掉 -C incremental=… ⇒ sccache 不再拒缓存 ⇒ 缓存真正生效;
  • 增量编译产物(target/debug/incremental)不再产生 ⇒ 单这一项就少涨 12G。

代价与取舍:

  • 失去 cargo 自己的增量加速;
  • 由 sccache 命中替代,且跨 cargo clean 仍有效(增量缓存一 clear 就没了,sccache 命中不);
  • 「改一处重编」从「秒级(增量)」变成「秒级(缓存命中)」——实测命中率 86.71%。

3.2 清理动作

# 🔴 用 cargo clean,不要手 rm -rf target/
#   (cargo clean 会顺手清 target/ 外的残留,也避免路径写错)
cargo clean

实测输出与效果:

Removed 631330 files, 92.4GiB total
可用空间: 59 GiB → 118 GiB      磁盘占用: 87% → 75%

另删 scripts/__pycache__(124K,Python 字节码缓存,自动重建)。

⚠️ 「118 GiB / 75%」是清理完成那一刻的瞬时值 —— 随后跑 cargo test --workspace 会重新生成测试产物(target/ 3.5G),磁盘回落至 76% / 可用 110 GiB。 两个数都正常,看趋势别看快照。

⚠️ 清理前必须确认没有构建在跑:

pgrep -f "cargo (build|rustc|check)" && echo "有构建在跑,先别清"

这条闸门与 xstudio/scripts/reclaim-space.sh 的做法一致(pgrep 探测活跃构建则跳过)。

3.3 验证:清空后重建走缓存命中

这是判断「根治了没有」的决定性实验:

场景 耗时
全量首次编译(无缓存) 63s
rm -rf target 后重建(走 sccache 命中) 14.14s ✅

命中率 86.71%(124 命中 / 19 未命中)。target/debug/incremental 不再产生 (实测只剩 0B 空目录)。


4. 结果

指标 处置前 处置后
target/ 58G 1.2G(纯构建)/ 3.5G(含测试产物)
target/debug/incremental 12G 0B(不再产生)
磁盘占用 87% 75%(清理瞬时)→ 76%(跑完测试后)
可用空间 59 GiB 118 GiB(清理瞬时)→ 110 GiB(含测试产物)
清空后重建 63s(全量) 14.14s(缓存命中)
sccache 命中率 0% 86.71%

无回归(全部复跑确认):

  • cargo test --workspace:695 passed / 0 failed / 2 ignored(79 个二进制,与 M1 基线完全一致)
  • check-arch 20/20 · check-boundary 12/12 · check-contract 10/10
  • check-module 123/123 · check-citations 4/4

5. 沉淀下来的规矩

  1. target/ 现在是「随时可清」的东西 —— 清了重建只要十几秒,不必心疼。 真要清用 cargo clean,不要手 rm -rf target/。
  2. 清之前先 pgrep —— 有构建在跑就跳过,别把别人的编译现场掀了。
  3. sccache 缓存在 ~/.cache/sccache,不在项目内 ⇒ 跟着 target/ 一起删是错的。 它是包缓存(按既定约定统一放 ~/.cache/<tool>/,工具默认路径留软链)。
  4. 改 Cargo.toml 的 profile 参数要重新体检 target 体积 —— profile 一变,cargo 会留一整套旧产物(本次就积累了 10 个 rlib ≈ 1.7G)。
  5. 发现 sccache 命中率异常时,看 server 端日志(SCCACHE_LOG=debug + SCCACHE_ERROR_LOG),client 端统计只说「没命中」,不说「为什么」。
  6. cargo metadata 在本机可能失败 —— 它要拉 wasm 依赖(如 js-sys), --offline 下报 failed to download。统计依赖规模用 Cargo.lock 的 [[package]] 数。

6. 相关文件

文件 作用
Cargo.toml(根) [profile.dev] incremental = false —— 修复点本体
~/.cargo/config.toml rustc-wrapper = sccache + SCCACHE_DIR(不是仓库内文件)
CLAUDE.md §9 「磁盘占用」小节 —— 给 agent 的速查摘要
xstudio/scripts/reclaim-space.sh 兄弟项目的同类回收脚本(pgrep 闸门 + 只清可再生中间产物的口径可参考)

相关 tag:v0.1.8-target-cleanup(本处置)