modref

按安装输入文件的内容哈希缓存 node_modules，再把各份 node_modules 绝对符号链接回仓库。当前目录向上查找 modref.json。

不要在项目里直接 pnpm install / pnpm add。 一律走 modref install / modref add。pnpm 不允许对已经是 symlink 的 node_modules 再 install（会 ENOTDIR）；modref 在缓存树里安装再链回来，绕开这条限制。

安装

需要 Node.js >= 18，以及本机已安装 pnpm。

cd packages/modref
npm install
npm run build
npm link

之后可在任意目录使用 modref。

Windows：node_modules 使用目录联接（junction），不是 .lnk 快捷方式（Node 无法把 .lnk 当目录解析）。跨盘时会回退到目录符号链接，需要打开「开发人员模式」。pnpm 按 pnpm.cmd / pnpm.exe 查找，也可设置环境变量 PNPM。

配置

在仓库根目录（或任意父目录）放一份 modref.json。cache_dir 必须是绝对路径。工作区盘很小、不能再放下一份 node_modules 时，必须把缓存放到另一块数据盘（CloudIDE 本环境是 /data）：

{
  "cache_dir": "/data/modref-cache",
  "projects": [
    { "dir": "haems-app", "name": "haems-app" },
    { "dir": "haems-vue", "name": "haems-vue" }
  ]
}

dir 相对配置文件所在目录解析。pnpm store 在 cache_dir/store，与缓存树同盘才能 hardlink。

单包和 pnpm workspace 走同一条路径：根目录有 pnpm-workspace.yaml 就是 workspace，没有就是单包。不要在 modref.json 里列出子包。

shamefully_hoist 为 true 时，安装会带上 --shamefully-hoist（pnpm 11 已不再从 .npmrc 读这项）。各项目自己的 .npmrc 会拷进缓存树；app 已有 shamefully-hoist=true，vue 保持 isolated linker。顶层开关只是可选覆盖。

缓存树安装会打开 dangerously-allow-all-builds，否则 pnpm 10+ 会拦截依赖的构建脚本（node-sass / esbuild 等）并报 ERR_PNPM_IGNORED_BUILDS。

overrides 按 git 分支名覆盖包版本，只写进缓存树（pnpm.overrides），不改仓库里的 package.json。也可以写在某个 projects[] 项上，会覆盖顶层同名配置。安装了 modref hook 后，创建或切换分支会自动执行 modref install。

使用

# /root/workspace/modref.json
# cache_dir = /data/modref-cache

cd /root/workspace/haems-vue && modref install
cd /root/workspace/haems-app && modref install

# 以后加依赖（在子包目录则加到该子包）
cd /root/workspace/haems-vue/apps/web-antd && modref add lodash

哈希来自 lockfile、pnpm-workspace.yaml、各 package.json、.npmrc、patches 等安装输入，外加 platform-arch。只改业务 src 再 modref install 是 cache hit。

物化在缓存树里执行 pnpm install --ignore-scripts 再 pnpm rebuild（编原生绑定，不跑 husky / 根 postinstall）。回链之后，若根 package.json 有 postinstall（例如 vue 的 stub），在真实仓库里跑，以便读到工作区源码。

项目里的 node_modules（含 workspace 子包下的）全部是指向 cache_dir/<name>/<hash>/... 的绝对 symlink。切 git 分支走现有 modref checkout / hook；缺树则 modref install。

Git 钩子

modref hook

在各项目的 git 仓库安装 post-checkout 钩子。创建或切换分支（git checkout / git switch 的分支操作，不含检出文件）时自动执行 modref install --all。