Files
dev-cache-layout/SKILL.md
T
ssw 638cbc90d7 feat: dev-cache-layout skill 初始提交
- 两条铁律:构建中间产物不外移、包缓存统一 ~/.cache/<tool>/
- 当前映射表(cargo/pnpm/npm/sccache 实测状态)
- sccache 0.18 唯一生效配置方式:SCCACHE_DIR 环境变量
- sccache 与增量编译互斥的说明及 cargo cold 别名
2026-10-23 08:51:50 +08:00

6.9 KiB
Raw Blame History

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 定,全机通用)

  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-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% 命中)。

新工具接入 / 新机器复现(套路固定四步)

  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 的),写 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,不要在这里重复维护。