--- name: dev-cache-layout description: 统一管理本机构建缓存布局——构建中间产物留项目目录、包管理器缓存实体统一 ~/.cache// 且工具默认路径留软链。当需要决定某构建产物该放哪、审计缓存分布、新机器/新工具接入缓存布局、或纠正缓存外移误操作时使用。触发词:缓存布局、缓存软链、~/.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//`,工具**默认路径留 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: ```bash 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/` → `mv <默认路径> ~/.cache//<名字>` → `ln -s ~/.cache//<名字> <默认路径>`。 4. 验证默认路径仍解析:`pnpm store path`、`npm config get cache`、`cargo --version`,并跑一次安装/构建确认软链透明。 工具没有默认路径概念时(sccache 这类靠 env 的),写 shell env + `~/.cargo/config.toml` 的 `[env]`,**不要**用软链。 ## 审计(随时可跑) ```bash 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`,不要在这里重复维护。