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

90 lines
6.9 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
---
name: dev-cache-layout
description: 统一管理本机构建缓存布局——构建中间产物留项目目录、包管理器缓存实体统一 ~/.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:
```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/<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]`,**不要**用软链。
## 审计(随时可跑)
```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`,不要在这里重复维护。