影响:
- 技能从「结构同构但无编译缓存」升级为「已落地」: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 后接中文)。
- 映射表补实测体积与状态列;审计命令、反模式清单各补数条;新增「边界」小节。
18 KiB
name, description
| name | description |
|---|---|
| dev-cache-layout | 统一管理本机构建缓存布局——构建中间产物留项目目录、包管理器缓存实体统一 ~/.cache/<tool>/ 且工具默认路径留软链。当需要决定某构建产物该放哪、审计缓存分布、新机器/新工具接入缓存布局、判断项目中间产物能否清理、或纠正缓存外移误操作时使用。触发词:缓存布局、缓存软链、~/.cache、pnpm store、cargo registry、npm cache、bun globalStore、sccache、缓存外移、统一缓存、cache layout、target 太大、能否清理、reclaim。 |
dev-cache-layout · 本机构建缓存布局
两条铁律(2026-10-18 定,全机通用)
- 构建中间产物不外移。cargo
target/、SwiftPM.build/、dist/、*.o等是项目自己的可再生产物:有用就留在项目目录里(增量编译/复查),没用就让构建工具或清理脚本删。严禁 mv 到~/Library/Caches/xxx-target之类"假缓存"再软链回来——软链不被.gitignore的目录型规则(.../target/)匹配,git status 会冒出??,且缓存脱离项目生命周期,纯负优化。 - 包缓存才统一。包管理器的下载缓存/全局 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:
[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。
验证:
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 本机就因此误判过一次。判断方法:
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(临时关增量):
cargo cold # = build --config profile.dev.incremental=false,清 target/切分支/升级依赖后用
cargo coldcheck # 同上,check 版本
冷启动量级参考(旧机实测,非本机):61.8s(增量开,sccache 不参与)→ 36.5s(cargo cold,100% 命中)。
项目内中间产物:什么时候可以清
中间产物按铁律 #1 留在项目里,但留不等于永远不删。判断顺序:
- 先确认它可再生产:
git check-ignore -v <dir>命中 ignore 规则(如plugins/*/rust/target);git ls-files <dir>为空。 - 再确认成品已另有落点:xstudio 插件这类,
Resources/<name>.dylib与rust/target/release/<name>.dylib应大小 + mtime 完全一致(ls -la对比),说明 target 里没有独有内容;包已进dist/。 - 用工具原生命令删,别
rm -rf:cargo clean --manifest-path <crate>/Cargo.toml(会同步 cargo 记账)、swift package clean。 - 记下重建代价: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 上(本机已验证)
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 副本)。
四个必须知道的坑:
- 必须
-explicit-module-build。否则只 warning 一句-cache-compile-job cannot be used without explicit module build, turn off caching就静默关掉缓存——最阴的失败模式,务必用-Rcache-compile-job确认真的有 replay/miss。 -j必须压到 ≤4。本机默认 j12 时会在"并行编译 SDK 模块"阶段被 SIGKILL(32G 内存照样死);j4 稳定。swift build setup里报 137 先怀疑并发。- 首次带 flag 的构建会全量重编:编译命令行变了,既有
.build(不带 flag 产的)基本失效。别在赶时间时切换。 - 本机 6.3.3 没有
--experimental-explicit-module-build(那是个别版本的隐藏选项),只能用-Xswiftc传。 - 全量重编时链接阶段会刷一批
llvmcas://<hash>: No such file or directory警告(xstudio 实测 114 条,紧跟[n/m] Write Objects.LinkFileList)。实测无害:同一次构建rc=0、产物与未开 CAS 的同类构建size -m的__TEXT/__text段大小逐字节一致。判断这类警告是否真丢对象,看段大小/符号,不要凭警告条数慌。 - 写脚本时
$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。迁移时这两个入口要一起改指向。
新工具接入 / 新机器复现(套路固定四步)
- 找默认路径:
pnpm store path/npm config get cache/bun pm cache/ cargo 即$CARGO_HOME/{registry,git}。 - 先停掉会写这个目录的进程(cargo / bacon / rust-analyzer / pnpm / 打包任务),否则 mv 会撞上"目录非空/文件正在写"。
mkdir -p ~/.cache/<tool>→mv <默认路径> ~/.cache/<tool>/<名字>→ln -s ~/.cache/<tool>/<名字> <默认路径>。- 验证默认路径仍解析:
pnpm store path、npm config get cache、cargo --version,并跑一次安装/构建确认软链透明。
工具没有默认路径概念时(sccache 这类靠 env 的),写 ~/.cargo/config.toml 的 [env] + relative = true(如上),不要用软链、不要写死 home。
审计(随时可跑)
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,不要在这里重复维护。