Files
admin b4208e4673 docs: 补 SwiftPM CAS 落地、中间产物清理判据(2026-10-23 实测)
影响:
- 技能从「结构同构但无编译缓存」升级为「已落地」:swiftc 的 CAS 可经 -Xswiftc 透传给 SwiftPM,
  xstudio 已接进 start-xstudio.sh --rebuild(清 .build 重编 204.6s → 34.8s,5.9×)。
- 新增「项目内中间产物什么时候可以清」四步判断,避免把可再生产物当垃圾、或把发布物删掉。

改动:
- sccache 接法改为可移植写法 `relative = true`(cargo `[env]` 不展开 $HOME/~/`${HOME}`,实测原样透传)。
- 新增陷阱:`du -sh` 不跟随符号链接 → 默认路径报 0B / stats 报默认路径不等于缓存分裂(用 `du -sh -H`、`ls -la` 看箭头)。
- 修正过度断言「增量开则 hits 恒为 0」:release 构建近乎全可命中(dbx 2147 hits/2 miss)。
- 补 SwiftPM 一节:官方 SE-0547 状态、可用命令、6 行实测对照、6 个坑(静默关闭、-j>4 SIGKILL、llvmcas 警告、$VAR 后接中文)。
- 映射表补实测体积与状态列;审计命令、反模式清单各补数条;新增「边界」小节。
2026-10-23 11:42:02 +08:00

208 lines
18 KiB
Markdown
Raw Permalink 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.
---
name: dev-cache-layout
description: 统一管理本机构建缓存布局——构建中间产物留项目目录、包管理器缓存实体统一 ~/.cache/<tool>/ 且工具默认路径留软链。当需要决定某构建产物该放哪、审计缓存分布、新机器/新工具接入缓存布局、判断项目中间产物能否清理、或纠正缓存外移误操作时使用。触发词:缓存布局、缓存软链、~/.cache、pnpm store、cargo registry、npm cache、bun globalStore、sccache、缓存外移、统一缓存、cache layout、target 太大、能否清理、reclaim。
---
# dev-cache-layout · 本机构建缓存布局
## 两条铁律(2026-10-18 定,全机通用)
1. **构建中间产物不外移**。cargo `target/`、SwiftPM `.build/`、`dist/`、`*.o` 等是项目自己的可再生产物:有用就留在项目目录里(增量编译/复查),没用就让构建工具或清理脚本删。**严禁** mv 到 `~/Library/Caches/xxx-target` 之类"假缓存"再软链回来——软链不被 `.gitignore` 的目录型规则(`.../target/`)匹配,git status 会冒出 `??`,且缓存脱离项目生命周期,纯负优化。
2. **包缓存才统一**。包管理器的下载缓存/全局 store,实体放 `~/.cache/<tool>/`,工具**默认路径留 symlink 指过去**:默认路径对工具透明可用,实体全机一份、集中在 `~/.cache` 可视可管。选 `~/.cache`(通用模式)而非自创路径(如 `~/caches`)。
## 当前映射(2026-10-23 实测状态)
| 工具 | 默认路径 | 实体位置 | 状态 |
|---|---|---|---|
| cargo registry | `~/.cargo/registry`(symlink) | `~/.cache/cargo/registry` | ✅ 169M |
| cargo git deps | `~/.cargo/git` | `~/.cache/cargo/git` | — 本机无 git 依赖,目录不存在 |
| SwiftPM 包缓存 | `~/Library/Caches/org.swift.swiftpm`(另有 `~/.swiftpm/cache` 软链入口) | 仍在 `~/Library/Caches`(未统一) | ⏳ 398M(repositories 395M),待迁 `~/.cache/swiftpm` |
| sccache | `~/Library/Caches/Mozilla.sccache`(symlink) | `~/.cache/sccache` | ✅ 2.5G(`du`)/ 3 GiB(stats 逻辑值),上限 10 GiB |
| pnpm store v10 | `~/Library/pnpm/store/v10`(symlink) | `~/.cache/pnpm/store/v10` | ✅ 2.2G |
| pnpm metadata/dlx | `~/Library/Caches/pnpm`(symlink) | `~/.cache/pnpm/metadata` | ✅ 2.0M |
| npm cache | `~/.npm`(symlink) | `~/.cache/npm` | ✅ 1.0G |
| bun globalStore | `~/.bun/install/cache` | `~/.cache/bun/cache` | — bun 未安装 |
全部包缓存实体已集中在 `~/.cache`。工具视角路径不变:`pnpm store path` 返回 `~/Library/pnpm/store/v10`、`npm config get cache` 返回 `~/.npm`,软链对工具透明。
`~/.cargo/bin`(rustup shims)、`~/.cargo/config.toml`、`~/.cargo/credentials.toml` 留在 `~/.cargo` 原地——那是工具本体/配置,不是缓存,不外迁。
## sccache 的正确接法(2026-10-22 纠错 + 2026-10-23 可移植化)
**sccache 0.18 不读任何 config 文件**。实测以下路径写了都不生效:
- `~/.config/sccache/config`(旧文档说的位置)
- `~/Library/Application Support/sccache/config`(macOS config_dir)
- `{"cache":{"type":"local","dir":...}}` 和 `{"cache_dir":...}` 两种格式都试过,均无效
**唯一生效方式:`SCCACHE_DIR` 环境变量**。写进 `~/.cargo/config.toml` 的 `[env]` 表——cargo 拉起的构建(含 IDE / rust-analyzer / CI,不经 shell 的也带上)全部继承,不依赖 shell export:
```toml
[env]
SCCACHE_DIR = { value = ".cache/sccache", relative = true }
```
**不要写死 home 路径**(`/Users/<name>/.cache/sccache` 抄到别的机器就是废路径):
- cargo 的 `[env]` **不做** `$HOME` / `${HOME}` / `~` 展开——实测三者都被原样透传给子进程,sccache 会把字面量 `~` 当成相对当前目录的目录名建出来。
- `relative = true` 的基准是**含 `.cargo` 的那层目录**,即 `$CARGO_HOME` 的父目录、通常就是 `$HOME`:`value=".cache/sccache"` → `$HOME/.cache/sccache`。换机器/换用户名零改动。
- 本机(cargo 1.95.0)已用该写法实测:`cargo build` 拉起的 server 报 `Cache location: $HOME/.cache/sccache`。
验证:
```bash
sccache --stop-server # 旧 server 不重启不会换配置
cargo build -q --manifest-path <某工程>/Cargo.toml # 触发由 cargo 拉起的 server
sccache --show-stats | grep "Cache location" # 必须是 $HOME/.cache/sccache
```
若仍显示默认路径,说明连的是**旧 server 实例**(`sccache --stop-server` 后重新构建);本机默认路径 `~/Library/Caches/Mozilla.sccache` 本身是指向 `~/.cache/sccache` 的 symlink,因此即便落到默认路径也不会分叉(见下条陷阱)。
### 陷阱:`du -sh` 不跟随符号链接
`sccache --show-stats` 报"默认路径"、`du -sh ~/Library/Caches/Mozilla.sccache` 报 `0B`,**不代表缓存分裂**——很可能那是个 symlink(`du` 默认只统计链接本身)。2026-10-23 本机就因此误判过一次。判断方法:
```bash
ls -la ~/Library/Caches/ | grep -i sccache # 看箭头:xxx -> /Users/.../.cache/sccache
du -sh -H ~/Library/Caches/Mozilla.sccache # -H 跟随命令行上的符号链接,才给出真实体积
```
`readlink` / `stat -f %N` 也可;注意 `stat` 不带 `-L` 拿到的也是链接自身 inode。
### sccache 与增量编译的关系(2026-10-23 修正)
cargo 默认开 incremental,rustc 带 `-C incremental` 的 crate 会被 sccache 判 non-cacheable。**但 debug profile 的增量只对 workspace members 和 path 依赖开**,registry 依赖默认不带该 flag,因此仍是 sccache 的主力命中面。
- release 构建(`build_plugins.py` 这类)几乎全可缓存。本机实测清空 target 后全量重编:dbx **2147 hits / 2 miss(99.91%)**,wb+pencil **24 hits / 0 miss**;non-cacheable 只剩 cdylib 链接、proc-macro、cargo 探针。
- 日常 dev 想榨依赖层缓存,用 `~/.cargo/config.toml` 里的 alias(临时关增量):
```bash
cargo cold # = build --config profile.dev.incremental=false,清 target/切分支/升级依赖后用
cargo coldcheck # 同上,check 版本
```
冷启动量级参考(旧机实测,非本机):61.8s(增量开,sccache 不参与)→ 36.5s(`cargo cold`,100% 命中)。
## 项目内中间产物:什么时候可以清
中间产物按铁律 #1 留在项目里,但**留不等于永远不删**。判断顺序:
1. **先确认它可再生产**:`git check-ignore -v <dir>` 命中 ignore 规则(如 `plugins/*/rust/target`);`git ls-files <dir>` 为空。
2. **再确认成品已另有落点**:xstudio 插件这类,`Resources/<name>.dylib` 与 `rust/target/release/<name>.dylib` 应**大小 + mtime 完全一致**(`ls -la` 对比),说明 target 里没有独有内容;包已进 `dist/`。
3. **用工具原生命令删**,别 `rm -rf`:`cargo clean --manifest-path <crate>/Cargo.toml`(会同步 cargo 记账)、`swift package clean`。
4. **记下重建代价**:sccache 命中前提下,dbx 全量重建仍约 **29m32s**(时间主要花在取缓存产物 + 链接 69MB dylib + 打包签名,不是编译);wb/pencil 各约 2 分钟;SwiftPM `.build` 重建取决于包数。
**不能清**:`Resources/`(入 Git 的发布物,xstudio.dbx 685 个前端文件、pencil 的 CanvasKit WASM)、`<crate>/rust/vendor`(`--offline` 构建的依赖源,删了必须联网)、`panel/` 与 `manifest.json` 等源码。
本机参考量级(2026-10-23):`plugins/` 4.3G → 清掉三个 `rust/target`(dbx 1.7GiB/5538 文件 + wb 35.8MiB + pencil 35.4MiB)后 2.5G。同层可再回收的是 SwiftPM `.build/`(remote 689M、code 308M、design 289M)与 `remote/web/node_modules` 187M。
在 WorkBuddy 沙箱里跑 xstudio 打包脚本时加 `CODEBUDDY_SAFE_DELETE_ENABLED=0`,否则 `plugins/dist/.stage`(688 文件 > 批量删除阈值 50)会因守卫拦下残留约 103M。
## SwiftPM:结构同构,编译缓存官方未落地但可手动挂(2026-10-23 实测)
cargo 的三层映射在 Swift 侧一一对应,差别只在编译结果缓存这层"官方没给开关、但编译器本身有":
| 层 | Rust | SwiftPM | 处理口径 |
|---|---|---|---|
| 项目内中间产物 | `target/` | `.build/`(= `swift build` 的 scratch path) | 同铁律 #1:留项目内;清理用 `swift package clean` 或删 `.build` |
| 包缓存实体 | `~/.cargo/registry` | `~/Library/Caches/org.swift.swiftpm`(`repositories` 395M = 裸仓镜像,`manifests` 3.1M) | 可统一到 `~/.cache/swiftpm` + 软链(**本机尚未迁移**) |
| 工具配置 | `~/.cargo/config.toml` | `~/Library/org.swift.swiftpm/{configuration,security}` | 不迁(是配置不是缓存) |
| 编译结果缓存 | sccache | 官方 flag 未落地,但 **swiftc 自带 CAS**,已用 `-Xswiftc` 挂进 `start-xstudio.sh --rebuild`(见下) | 已落地 |
### 官方状态(别等错版本)
SE-0547 于 **2026-10-08 accepted**,接口是 `swift build --enable-build-caching` / `--build-cache-path` / `swift package build-cache`。但 **Swift 6.4 是 9 月发布的、早于 acceptance**,所以 6.4 里也没有;本机 CLT **Swift 6.3.3 实测三个 flag 全是 `error: Unknown option`**。→ 官方开关最早 6.5,届时优先用它(自带 prefix mapping、size limit、eviction)。
### 当下可用:把 swiftc 的 CAS 挂到 SwiftPM 上(本机已验证)
```bash
swift build --disable-sandbox -j 4 \
-Xswiftc -explicit-module-build \
-Xswiftc -cache-compile-job \
-Xswiftc -cas-path -Xswiftc "$HOME/.cache/swift-cas"
# 诊断时再加:-Xswiftc -Rcache-compile-job (stdout 里出现 remark: replay / cache miss)
```
**xstudio 已把它接进 `start-xstudio.sh` 的 `--rebuild` 分支**(2026-10-23,函数 `swift_build_cached`):只在 `--rebuild` 生效(日常启动不编译,不付 CAS 开销);`XSTUDIO_SWIFT_CAS=0` 关断,`XSTUDIO_SWIFT_CAS_DIR` / `XSTUDIO_SWIFT_JOBS` 可调。**该脚本里的两处 `swift build`(正常 rebuild + 增量漏检兜底的清 `.build` 重编)必须共用这一个函数**——命令行一变,SwiftPM 就把既有 `.build` 判失效、白全量重编。旁证:`market_e2e.sh` / `verify-native-plugin.sh` 各用独立 `--scratch-path`,互不影响。
xstudio `source/`(399 个 .swift,`-j 4`,清空 scratch 重建)实测:
| 场景 | 耗时 | 说明 |
|---|---|---|
| 裸冷构建(无任何 flag) | **204.6s** | 基线 |
| CAS 冷构建(缓存为空) | **363.2s** | +78%,一次性填充;334 次 miss |
| CAS 清空 `.build` 重建(缓存已热,独立探针) | **21.6s** | 16284 replay / 0 miss,9.5× |
| 同上,走 `start-xstudio.sh --rebuild` 的真实配置 | **36s** | 5.9×;多出的时间是链接 30MB debug 主程序 + `Applying`,CAS 只新写 5MB |
| 改 flag 后首次 `--rebuild` | **127s** | 566 单元全量重编,CAS 部分命中(旧缓存是另一路径建的) |
| 随后空跑 `--rebuild` | **1.8s**(含等待共 5s) | 增量照常,CAS 开销可忽略 |
盈亏平衡点:一次热重建就赚回冷启动开销;但**如果这台机器只做一次冷构建**(首次拉代码),带 flag 反而更慢。CAS 体积:该项目约 **664M**(`~/.cache/swift-cas`,符合铁律 #2;探针版已并入,别留 `swift-cas-probe` 副本)。
四个必须知道的坑:
1. **必须 `-explicit-module-build`**。否则只 warning 一句 `-cache-compile-job cannot be used without explicit module build, turn off caching` 就**静默关掉缓存**——最阴的失败模式,务必用 `-Rcache-compile-job` 确认真的有 replay/miss。
2. **`-j` 必须压到 ≤4**。本机默认 j12 时会在"并行编译 SDK 模块"阶段被 SIGKILL(32G 内存照样死);j4 稳定。`swift build setup` 里报 137 先怀疑并发。
3. **首次带 flag 的构建会全量重编**:编译命令行变了,既有 `.build`(不带 flag 产的)基本失效。别在赶时间时切换。
4. 本机 6.3.3 **没有** `--experimental-explicit-module-build`(那是个别版本的隐藏选项),只能用 `-Xswiftc` 传。
5. **全量重编时链接阶段会刷一批 `llvmcas://<hash>: No such file or directory` 警告**(xstudio 实测 114 条,紧跟 `[n/m] Write Objects.LinkFileList`)。实测**无害**:同一次构建 `rc=0`、产物与未开 CAS 的同类构建 `size -m` 的 `__TEXT`/`__text` 段大小逐字节一致。判断这类警告是否真丢对象,看段大小/符号,不要凭警告条数慌。
6. **写脚本时 `$VAR` 后紧跟中文/全角字符必须写 `${VAR}`**:bash 会把多字节字符当变量名的一部分——`$SWIFT_CAS_DIR(关闭用…` 实测整段路径被吞、终端打出乱码。这条与缓存无关,但是改造那段 echo 时踩到的真坑。
### 其他路为什么不走
- `ccache 4.13.6` 只包装 clang/GCC 系(C/C++/ObjC),**不接 swiftc**;`sccache` 也不支持 Swift。
- Xcode 26 的 CAS 编译缓存与本机制**同一套基础设施、可共享同一 CAS 路径**(SwiftPM 作者在 SE-0547 评审里确认),但需要完整 Xcode + xcodebuild;本机只有 CLT,xstudio 走 `swift build` → 用不上。
- NativeLink / Buildless / Bazel / Buck2 都声称支持 Swift 缓存,但要求把构建迁到 Bazel/Buck 的 action graph——对 SwiftPM 项目等于重写构建,不成立。
### 两个实践要点
- 受限 shell 里跑 `swift build` / `swift package` 必须加 `--disable-sandbox`(SwiftPM 默认套 sandbox-exec,会报 `sandbox_apply: Operation not permitted`;xstudio 的 `start-xstudio.sh` 正是这么调的)。
- 本机 `~/.swiftpm/{cache,configuration,security}` 三个入口已是软链,分别指向 `~/Library/Caches/org.swift.swiftpm`、`~/Library/org.swift.swiftpm/{configuration,security}`——即"Linux 风格视图 → macOS 实体位置"的映射,**不等于**已按铁律 #2 统一进 `~/.cache`。迁移时这两个入口要一起改指向。
## 新工具接入 / 新机器复现(套路固定四步)
1. 找默认路径:`pnpm store path` / `npm config get cache` / `bun pm cache` / cargo 即 `$CARGO_HOME/{registry,git}`。
2. **先停掉会写这个目录的进程**(cargo / bacon / rust-analyzer / pnpm / 打包任务),否则 mv 会撞上"目录非空/文件正在写"。
3. `mkdir -p ~/.cache/<tool>` → `mv <默认路径> ~/.cache/<tool>/<名字>` → `ln -s ~/.cache/<tool>/<名字> <默认路径>`。
4. 验证默认路径仍解析:`pnpm store path`、`npm config get cache`、`cargo --version`,并跑一次安装/构建确认软链透明。
工具没有默认路径概念时(sccache 这类靠 env 的),写 `~/.cargo/config.toml` 的 `[env]` + `relative = true`(如上),**不要**用软链、不要写死 home。
## 审计(随时可跑)
```bash
du -sh ~/.cache/* 2>/dev/null # 包缓存实体都应在 ~/.cache 下
ls -la ~/.cargo ~/.npm ~/.bun/install ~/Library/pnpm/store ~/Library/Caches/pnpm ~/Library/Caches/ 2>/dev/null | grep -- '->'
du -sh -H ~/Library/Caches/Mozilla.sccache # 跟随软链看真实体积(勿用 du -sh 判 0B)
du -sh ~/Library/Caches/org.swift.swiftpm ~/.swiftpm/cache 2>/dev/null # SwiftPM 包缓存(未统一时实体在 Library)
du -sh ~/.cache/swift-cas 2>/dev/null # Swift 编译 CAS(xstudio 约 664M;~/.cache/swift-cas-probe 是废弃探针,应已并入)
ls -la ~/.swiftpm | grep -- '->' # 三个入口应指向已统一的位置
sccache --show-stats | grep -E "Cache location|Cache size" # location 必须是 $HOME/.cache/sccache
find ~/Documents -maxdepth 5 -type l -lname '*Library/Caches*' 2>/dev/null # 应只剩白名单(若有)
```
## 清理原则
- 只清**可再生**缓存;`node_modules` / pnpm store / cargo registry / go modcache / `~/.gradle` / `~/.m2` **不删**(删了要重下重编,反模式)。瘦身用工具自己的 prune:`pnpm store prune`、`bun pm cache prune`、`go clean -cache`(勿 `-modcache`)、`sccache --stop-server` + 删 `~/.cache/sccache`(会丢编译缓存,慎用)。
- 项目内中间产物按上节四步判断后 `cargo clean` / `swift package clean`;xstudio 工作区还有 `bash scripts/reclaim-space.sh`(带活跃构建 pgrep 闸门;`refs/*` 放 `.xstudio-keep` 可豁免)。
- macOS 删个人文件必须进回收站(见用户级记忆);`rm` 只用于自建临时物。
- "删除式清磁盘"诉求可用市场里的「磁盘清理」技能;本技能只管布局 + 中间产物去留判断。
## 反模式清单
- 把 `target/` mv 到 `~/Library/Caches` 再软链回项目(2026-10-18 已全部回迁纠正)
- `rm -rf node_modules` / pnpm store / `~/.cargo/registry` / `~/.gradle` / `~/.m2`
- 给每个项目单独 copy 一份依赖 store(vs 全局 store + 软链)
- 用非标准路径(如 `~/caches/`)而不是 `~/.cache/`
- 以为写了 sccache 的 config 文件就生效了(必须 env + 重启 server 验证)
- 在 `[env]` 里写死 `/Users/<name>/...`,或指望 `$HOME`/`~` 展开(cargo 不展开,实测原样透传)
- 看到 `du -sh` 报 `0B` / stats 报默认路径就断言"缓存分裂"(先用 `ls -la` 看是不是 symlink、`du -sh -H` 复测)
- 以为裸 `swift build` 有 sccache 级缓存、随手清 `.build`(裸调用没有,清了就是真重编;但挂上 CAS flag 后另说——两种模式别混谈)
- 只加 `-cache-compile-job` 不加 `-explicit-module-build`,然后看日志没报错就以为生效了(会被静默关闭,必须看 `-Rcache-compile-job` 的 replay/miss)
- 把 `~/.swiftpm/cache` 当成"已统一进 `~/.cache`"(它只是指向 `~/Library/Caches/org.swift.swiftpm` 的入口,实体仍在 Library)
- 迁移 `~/.cargo/registry` 时不停 cargo/bacon/rust-analyzer
- 用 `rm -rf` 删 `target/`(丢 cargo 记账,且沙箱批量删除还会撞守卫)
## 边界
本技能管**布局**(东西放哪、怎么统一)与**项目中间产物能不能清**。依赖下载提速(镜像源)与编译提速(jobs/sccache profile)属于另一层,配置在 `~/.cargo/config.toml` 与 `~/.zshrc`,不要在这里重复维护。