新增 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 全绿。
8.4 KiB
编译膨胀问题及处理(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-arch20/20 ·check-boundary12/12 ·check-contract10/10check-module123/123 ·check-citations4/4
5. 沉淀下来的规矩
target/现在是「随时可清」的东西 —— 清了重建只要十几秒,不必心疼。 真要清用cargo clean,不要手rm -rf target/。- 清之前先
pgrep—— 有构建在跑就跳过,别把别人的编译现场掀了。 sccache缓存在~/.cache/sccache,不在项目内 ⇒ 跟着target/一起删是错的。 它是包缓存(按既定约定统一放~/.cache/<tool>/,工具默认路径留软链)。- 改
Cargo.toml的 profile 参数要重新体检 target 体积 —— profile 一变,cargo 会留一整套旧产物(本次就积累了 10 个 rlib ≈ 1.7G)。 - 发现 sccache 命中率异常时,看 server 端日志(
SCCACHE_LOG=debug+SCCACHE_ERROR_LOG),client 端统计只说「没命中」,不说「为什么」。 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(本处置)