- 两条铁律:构建中间产物不外移、包缓存统一 ~/.cache/<tool>/ - 当前映射表(cargo/pnpm/npm/sccache 实测状态) - sccache 0.18 唯一生效配置方式:SCCACHE_DIR 环境变量 - sccache 与增量编译互斥的说明及 cargo cold 别名
6.9 KiB
name, description
| name | description |
|---|---|
| dev-cache-layout | 统一管理本机构建缓存布局——构建中间产物留项目目录、包管理器缓存实体统一 ~/.cache/<tool>/ 且工具默认路径留软链。当需要决定某构建产物该放哪、审计缓存分布、新机器/新工具接入缓存布局、或纠正缓存外移误操作时使用。触发词:缓存布局、缓存软链、~/.cache、pnpm store、cargo registry、npm cache、bun globalStore、sccache、缓存外移、统一缓存、cache layout。 |
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-22 实测状态,pnpm/npm 于当日 17:52 完成迁移)
| 工具 | 默认路径 | 实体位置 | 状态 |
|---|---|---|---|
| cargo registry | ~/.cargo/registry(symlink) |
~/.cache/cargo/registry |
✅ 已落地 169M |
| cargo git deps | ~/.cargo/git |
~/.cache/cargo/git |
— 本机无 git 依赖,目录不存在 |
| sccache | SCCACHE_DIR(env,无默认路径概念) |
~/.cache/sccache |
✅ 已落地 38M |
| 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(cargo 169M + pnpm 2.2G + npm 1.0G + sccache 38M)。工具视角路径不变: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 纠错,重要)
sccache 0.18 不读任何 config 文件。实测以下路径写了都不生效(sccache --show-stats 里仍是默认的 ~/Library/Caches/Mozilla.sccache):
~/.config/sccache/config(旧文档说的位置)~/Library/Application Support/sccache/config(macOS config_dir){"cache":{"type":"local","dir":...}}和{"cache_dir":...}两种格式都试过,均无效
唯一生效方式:SCCACHE_DIR 环境变量。本机已双保险落地:
~/.cargo/config.toml的[env] SCCACHE_DIR = "/Users/rong/.cache/sccache"(任何经 cargo 的构建都带上,含 IDE/CI)~/.zshrc的同名 export(手动跑sccache命令时一致)
验证:sccache --show-stats | grep "Cache location" 应显示 ~/.cache/sccache。若还显示默认路径,说明是旧 server 实例没重启:sccache --stop-server 后再触发一次构建即可。
另注:sccache 与增量编译互斥——cargo 默认开 incremental,rustc 带 -C incremental 时 sccache 一律判 non-cacheable(sccache --show-stats 里表现为 Non-cacheable calls 增长、hits 恒为 0)。所以日常 dev 保持增量(1s 级)是对的,sccache 只在冷启动场景生效。为此在 ~/.cargo/config.toml 配了两个 alias:
cargo cold # = build --config profile.dev.incremental=false,清 target/切分支/升级依赖后用
cargo coldcheck # 同上,check 版本
本机实测冷启动 build:61.8s(增量开,sccache 不参与)→ 36.5s(cargo cold,sccache 100% 命中)。
新工具接入 / 新机器复现(套路固定四步)
- 找默认路径:
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 的),写 shell env + ~/.cargo/config.toml 的 [env],不要用软链。
审计(随时可跑)
du -sh ~/.cache/* 2>/dev/null # 包缓存实体都应在 ~/.cache 下
ls -la ~/.cargo ~/.npm ~/.bun/install ~/Library/pnpm/store ~/Library/Caches/pnpm 2>/dev/null | grep -- '->'
sccache --show-stats | grep "Cache location" # 必须是 ~/.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(会丢编译缓存,慎用)。 - 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 验证)
- 迁移
~/.cargo/registry时不停 cargo/bacon/rust-analyzer
边界
本技能只管布局(东西放哪、怎么统一)。依赖下载提速(镜像源)与编译提速(jobs/sccache/profile)属于另一层,配置在 ~/.cargo/config.toml 与 ~/.zshrc,不要在这里重复维护。