- 两条铁律:构建中间产物不外移、包缓存统一 ~/.cache/<tool>/ - 当前映射表(cargo/pnpm/npm/sccache 实测状态) - sccache 0.18 唯一生效配置方式:SCCACHE_DIR 环境变量 - sccache 与增量编译互斥的说明及 cargo cold 别名
90 lines
6.9 KiB
Markdown
90 lines
6.9 KiB
Markdown
---
|
||
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`,不要在这里重复维护。
|