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:
1 parent
efb4cd6500
commit
a27389d0d0
3 files changed
+222
No files matched your search
@@ -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/
|
||||
```
|
||||
|
||||
|
||||
@@ -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`(本处置)
|
||||
Reference in new issue
Block a user