--- name: dev-cache-layout description: 统一管理本机构建缓存布局——构建中间产物留项目目录、包管理器缓存实体统一 ~/.cache// 且工具默认路径留软链。当需要决定某构建产物该放哪、审计缓存分布、新机器/新工具接入缓存布局、判断项目中间产物能否清理、或纠正缓存外移误操作时使用。触发词:缓存布局、缓存软链、~/.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//`,工具**默认路径留 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//.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 ` 命中 ignore 规则(如 `plugins/*/rust/target`);`git ls-files ` 为空。 2. **再确认成品已另有落点**:xstudio 插件这类,`Resources/.dylib` 与 `rust/target/release/.dylib` 应**大小 + mtime 完全一致**(`ls -la` 对比),说明 target 里没有独有内容;包已进 `dist/`。 3. **用工具原生命令删**,别 `rm -rf`:`cargo clean --manifest-path /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)、`/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://: 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/` → `mv <默认路径> ~/.cache//<名字>` → `ln -s ~/.cache//<名字> <默认路径>`。 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//...`,或指望 `$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`,不要在这里重复维护。