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 全绿。
This commit is contained in:
admin committed 2026-11-03 23:11:26 +08:00
1 parent efb4cd6500
commit a27389d0d0
3 files changed
+222

No files matched your search

+2
View File
@@ -13,6 +13,7 @@
- 📘 **契约唯一真源**:[`docs/contract.md`](contract.md) —— 与本文件冲突时以契约为准。
- 🧭 **agent 指引**:[`CLAUDE.md`](../CLAUDE.md)(红线 / 踩坑 / 端点全表)· [`HANDOFF.md`](../HANDOFF.md)(交接)。
- 🛠 **怎么起 / 怎么冒烟 / 常见故障**:[`docs/runbook.md`](runbook.md)。
- 💾 **编译膨胀问题及处理**:[`docs/build-bloat.md`](build-bloat.md)(`target/` 58G → 1.2G 的根因、处置与规矩)。
- 🧾 **实施期裁决(98 条「什么—为什么—代价」)**:[`docs/decisions.md`](decisions.md)
· **分支级已知限制**:[`docs/known-limitations.md`](known-limitations.md)。
@@ -56,6 +57,7 @@ ssw-jnpf-lite-rust/
├── scripts/smoke_backend.sh # 两把尺子的「隔离后端」自启动助手(默认自起 ⇒ CI 可跑)
├── scripts/check-module.sh # 业务模块 9 接触点静态自检(纯静态,不起后端)
└── docs/ # contract.md(契约)· runbook.md(运维)· decisions.md(裁决)· known-limitations.md(已知限制)
# build-bloat.md(编译膨胀问题及处理)
# JNPF_SOURCE_AUDIT.md(官方源码逐行核对)· JNPF_COMPAT_SURFACE.md(面 B 规格)· MIGRATION.md(迁移指南)· ddl/
```
+219
View File
@@ -0,0 +1,219 @@
# 编译膨胀问题及处理(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`(本处置)