From 638cbc90d71442e785be468c3f3bdffba3cdd704 Mon Sep 17 00:00:00 2001 From: ssw Date: Fri, 23 Oct 2026 08:51:50 +0800 Subject: [PATCH] =?UTF-8?q?feat:=20dev-cache-layout=20skill=20=E5=88=9D?= =?UTF-8?q?=E5=A7=8B=E6=8F=90=E4=BA=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 两条铁律:构建中间产物不外移、包缓存统一 ~/.cache// - 当前映射表(cargo/pnpm/npm/sccache 实测状态) - sccache 0.18 唯一生效配置方式:SCCACHE_DIR 环境变量 - sccache 与增量编译互斥的说明及 cargo cold 别名 --- SKILL.md | 89 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 89 insertions(+) create mode 100644 SKILL.md diff --git a/SKILL.md b/SKILL.md new file mode 100644 index 0000000..527df58 --- /dev/null +++ b/SKILL.md @@ -0,0 +1,89 @@ +--- +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`,不要在这里重复维护。