一个仓库里的「环境约束文件」考古

随便打开一个稍有年头的 Node.js 仓库，根目录大概率会有这几个文件：

• .nvmrc — 告诉 nvm / fnm / volta 用哪个 Node.js 版本
• .npmrc — registry、auth token、pnpm 行为、auto-install-peersshamefully-hoist 等杂物的栖息地
• package.json 的 engines.node — 给包管理器装依赖时做兜底校验
• package.json 的 packageManager — Corepack 用来固定 pnpm/yarn 版本

再看痛点。四份地方各管一摊，每次升级 Node 要改三处，新人入职得讲三遍「先 nvm use,再 corepack enable,registry 看一眼 .npmrc…，」。在 monorepo 里更糟糕：子项目要不要带自己的 .npmrc？话说回来，根目录的版本要不要往下复制？不留神，CI 用跑过本地又装出另一份 lockfile。

Pnpm 把这套东西收得相当彻底——只要愿意把 pnpm 升上去，本仓库里的 .nvmrc 和 .npmrc 都可以删掉。

.packageManager 字段：脱离 Corepack 自己工作

{ "packageManager": "pnpm@."}

说到痛点。Corepack 本身安装麻烦，Homebrew 装的 Node 默认禁用 Corepack，需要手动 corepack enable;公司网络下首次激活经常被代理卡住；COREPACK_ENABLE_AUTO_PIN 在某些版本会自动 package.json，反而搅乱 git diff。

Pnpm 给出了更优雅的回路：Pnpm 自己读 packageManager 字段。如果当前运行的版本对不上，就按 pmOnFail 设置来处理。新版默认 pmOnFail: download——直接下载对的版本接管这次调用。不动 package.json，不依赖 Corepack。

{ "devEngines": { "packageManager": { "name": "pnpm"。"version": ">=","onFail":"download" } } }

.engines.runtime / devEngines.runtime：pnpm 来管 Node、Bun、Deno

痛点的观点是。手动维护 .nvmrc 文件让团队协作变得繁琐，特别是跨网站开发者。每个人都需要在本地安装对应 Node/Bun/Deno 版本，才能跑一样的代码。

{ "engines": { "runtime": { "name":"bun","version":"*"。"onFail":"download" } } }

• engines.runtime：- 发布约束。声明此包对外发布时依赖哪个运行时pnpm 会把可执行文件绑死到指定 Node 版本。说起来，
• devEngines.runtime：- 项目约束。声明本地开发用的运行时在 pnpm install 时自动按版本下载到 pnpm-managed runtime store，并写进 lockfile。
• Pnpm install 一跑后正确版本的 Node/Bun/Deno 就到位了方法由 pnpm 注入到当前 shell。按理说，等价于 nvm use + “保证装过这个版本”。但不需要每个开发者本地都装 nvm。
• Pnpm CLI 一样可通过命令实现：pnpm runtime set node ,或者设置 bun/deno。该命令会写入 devEngines.runtime 并把版本固定下来。
• 旧的 pnpm env use 已被 pnpm runtime set 替代，两者效果相同；如果你之前使用 useNodeVersion 配置，现在必须迁到 devEngines.runtime。

至于痛点。过去我们频繁在 .npmrc 中配置 registry、proxy、auth 等，但这些配置被分散在多处，很难统一管理，也导致 CI 脚本复杂度提高。现在只能保留 auth / registry 两类配置，其余 pnpm 行为需搬家到 yaml 配置文件中。

# 示例迁移至 pnpm-workspace.yaml
registries:
default: https://registry.npmmirror.com/
"@my-org": https://private.example.com/
allowBuilds:
bun这方面。true
electron: true
core-js: false
packageConfigs:
apps/web:
saveExact:true
packages/sdk:
savePrefix:"~"
minimumReleaseAge:
strictDepBuilds:true

再看痛点，以前多文件导致维护成本高，新人上手慢；现在所有环境约束集中在单个 file，更易审计与协作。

json { "name"的观点是，"bolt","private":true,"packageManager":"pnpm@.","engines":{ "runtime":{ "name"这方面，"bun","version":"*","onFail":"download" } }。"devDependencies":{ "@typescript/native-preview":".-dev." } }

.nvmrc 不存在——实际跑在 Bun 上，engines.runtime 已钉住 Bun 版本，pnpm install 时按需下载。
• .npmrc 不存在——如果没有私有 registry 或镜像需求，则无需单独配置；若需要换 npm 镜像，只需单写一个 minimal .npmrc 即可。
pnpm install 即可，无需额外启用 Corepack 或手动切换 Node。`

配合月日那则笔记Bun 不再是 node_modules/.bin 的 devDependency，而是 pnpm runtime；调用直接 bun ...PATH 自动由 pnpm 接管。

四个文件压缩成了一个 package.json 的几个字段，实现一次配置即可满足团队、CI 与未来自我需求。

私有 registry / scope 映射：- 虽然 Pnpm 提供 registries 配置。但 npm 自身、CI 缓存层和其它工具链仍会读取 .npmrc，多写一份能省麻烦。`

我认为只要不出现 auth token 和私有 registry，就不必为 Pnpm 行为单独建 .npmrc。按理说，

1️⃣ 把 CI 和开发环境的 Node 升到 + 2️⃣ 在根 package.json 写 "packageManager":"pnpm@x.y.z" 并删掉 .nvmrc 3️⃣ 用 pnpx runtime set node x.x.x填好 devEngines.runtime必要时同步 engines.runtime 4️⃣ 跑 pnpx-v10-to-v11 codemod 自动迁 .npmrc 内非 auth 配置至 pnpx-workspace.yaml 5️⃣ 把 package.json 内 pnpx 字段配置挪至 pnpx-workspace.yaml;老实说，注意 onlyBuiltDependencies 已被 allowBuilds map 替代 6️⃣ CI 换掉 nvm use … 为 corepack enable && pnpx install 7️⃣ 第一次执行 pnpx install 后检查锁文件是否记录了 runtime 与 packageManagerDependencies 确认锁定生效 8️⃣ 删 .nvmrc,做一次完整冷启动验证

---
标签： 项目

---

• 上一篇： IfAI v0.4.8发布，对话能力提升10倍？
• 下一篇： MySQL慢查询优化，EXPLAIN分析助提升10倍性能！