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

220 lines
8.4 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 编译膨胀问题及处理(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:
```toml
[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 日志才看到真相:
```bash
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 会报错**):
```toml
[profile.dev]
incremental = false
```
**为什么这行有效**:
- 去掉 `-C incremental=…` ⇒ sccache 不再拒缓存 ⇒ 缓存真正生效;
- 增量编译产物(`target/debug/incremental`)不再产生 ⇒ 单这一项就少涨 **12G**。
**代价与取舍**:
- 失去 cargo 自己的增量加速;
- 由 sccache 命中替代,且**跨 `cargo clean` 仍有效**(增量缓存一 clear 就没了,sccache 命中不);
- 「改一处重编」从「秒级(增量)」变成「秒级(缓存命中)」——实测命中率 **86.71%**。
### 3.2 清理动作
```bash
# 🔴 用 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**。
> 两个数都正常,**看趋势别看快照**。
> ⚠️ **清理前必须确认没有构建在跑**:
> ```bash
> 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`(本处置)