Qiniu/technical/mac-dev-env-setup/node-nvm-pnpm.md

tags, create time

tags	create time
nodejs nvm pnpm dev-env	2026-07-01 00:00

Node.js + nvm + pnpm 详解

概述

Node.js 开发环境中版本管理和包管理的核心链路：nvm 控制运行时版本、Corepack 提供标准化的包管理器入口、pnpm 以高效磁盘模型取代传统的 flat install。三者配合形成完整的 JS/TS 工程基础。

核心概念

nvm 版本管理机制

nvm（Node Version Manager）的核心设计是通过 shell 函数劫持 node / npm / npx 命令：

# nvm 工作原理示意
which node
# → $(nvm_alias)/versions/node/*/bin/node   ← 实际是符号链接
#   ↑ 由 nvm 动态切换

操作	命令	说明
安装 LTS	nvm install --lts	自动检测最新 Long Term Support 版本
切换版本	nvm use <version>	修改 .nvmrc 或版本号
查看已装	nvm ls	列出版本树
设置默认	nvm alias default 20	每次打开终端自动激活
全局包复用	--reinstall-packages-from=<version>	切换时迁移全局包

# 在项目根目录创建 .nvmrc
echo "20" > .nvmrc

# nvm use 不加版本号时自动读 .nvmrc
cd my-project && nvm use
# → Found '/path/to/my-project/.nvmrc' with version <20>
# → Now using Node.js v20.18.0

[!tip] nvm 与 corepack 的交互 corepack prepare pnpm@latest --activate 安装的是 corepack 自己，nvm 切换 Node 版本后，corepack 依然存在——因为它是随 Node.js bundled 的（Node ≥ 16.13）。这意味着 不需要 在切换 Node 版本后重新安装 corepack。

Corepack 的作用

Corepack 是 Node.js 官方提供的零开销包管理器调度器，从 Node v16.13 起内置：

# Corepack 支持的包管理器
corepack enable        # 注册 pnpm / yarn / npm 的 shim 入口
corepack prepare pnpm@latest --activate  # 锁定 pnpm 版本

# 查看 corepack 管理的版本
corepack --version
corepack --enable

核心思想：让团队统一使用包管理器版本，而非各自在全局安装不同版本的 npm/yarn/pnpm。

# 项目中可指定 pnpm 版本
echo "pnpm@8.15.0" > .npmrc   # Corepack 读取

# 或直接通过 package.json
# (package.json 中添加 "packageManager": "pnpm@8.15.0")

CI 跑 corepack enable 即可自动下载指定版本，无需额外安装步骤。

pnpm 的存储模型

pnpm 最核心的创新在于 硬链接 + 内容寻址存储，解决了 npm/yarn 的两个经典问题：

1. 磁盘浪费：npm 在每个 node_modules 下复制依赖副本
2. 隐形依赖：flat tree 结构中子包能意外访问父包的依赖

传统 npm 安装（flat tree，symlink 树）
project-A/node_modules/
├── lodash/              ← symlink -> project-A/node_modules/lodash
├── express/             ← symlink -> project-A/node_modules/express
│   └── node_modules/
│       └── qs/          ← 可能被 project-B 重复安装

pnpm 安装（strict 模式）
pnpm-store/
├── .stores/v8/
│   └── abc123/          ← 内容哈希索引，全局唯一
│       ├── lodash.tgz
│       └── express.tgz
project-A/node_modules/
├── lodash/              ← hard link (硬链接) → .stores/v8/abc123/lodash.tgz
├── express/             ← hard link → .stores/v8/abc123/express.tgz
└── .pnpm/
    └── express@4.x/     ← nested symlink 满足 express 自身的 require('qs')

硬链接的优势：同样的文件在磁盘上只存一份，node_modules 中的硬链接不占用额外空间；而 symlink 在 Windows 上需要管理员权限才能创建。

[!warning] Windows 上的 pnpm Windows 10+ 支持硬链接，但默认可能需要开启"开发者模式"。如果遇到 permission denied，以管理员身份运行终端，或在系统设置中启用开发者模式。

pnpm workspace（Monorepo 支持）

{
  "name": "my-monorepo",
  "private": true,
  "workspaces": ["packages/*"]
}

workspace 模式下，同仓库内的包互相引用时直接使用硬链接，无需 publish：

cd packages/shared && pnpm add ../libs/core
# 等价于在 shared 的 package.json 中写了 "core": "link:../libs/core"

代码示例

项目级 .npmrc 推荐配置

# .npmrc
auto-install-peers=true
side-effects-cache=true   # 缓存 noSideEffects=true 的包，加快安装
shamefully-hoist=false    # 禁止非 hoist 提升到顶层
strict-peer-dependencies=true   # peerDependency 缺失时报错而非警告

快速诊断 node_modules 大小

# macOS/Linux
du -sh node_modules/

# 找出最大的前 10 个包
pnpm why --recursive | head -20

常见陷阱与最佳实践

1. nvm 与 Node.js 全局 CLI 丢失

切换 Node 版本后，之前在全局安装的 CLI 工具（如 typescript、eslint）不再可用，因为每个 Node 版本有独立的全局目录：

# 切换时保留全局包（仅同大版本间安全）
nvm use 20 --reinstall-packages-from=18

# 或者通用做法：CLI 工具放在工作区 root 的 devDependencies 中
pnpm add -D typescript eslint
npx tsc --version    # 始终能用

[!tip] 黄金法则：CLI 工具不进 global，进 devDependencies 所有团队工具的版本应该锁在 package.json 中，通过 npx <tool> 调用。这是避免"我的能跑你不行"问题的最根本策略。

2. Corepack 版本冲突

如果你的团队中有成员安装了独立的全局 pnpm，会与 Corepack 冲突：

# 检查当前 pnpm 来源
which pnpm
# → 应该是：$(corepack_dir)/pnpm → .corepack/pnpm → 目标二进制

# 卸载独立安装的全局 pnpm
npm uninstall -g pnpm

# 重新用 corepack 激活
corepack enable
corepack prepare pnpm@latest --activate

3. pnpm store 膨胀

pnpm 的内容寻址存储在反复安装/删除不同版本后会产生碎片：

# 清理未被任何 package.json 引用过的 store 条目
pnpm store prune

# 定期检查 store 大小
du -sh $(pnpm store path)

建议每月执行一次 pnpm store prune，通常能释放数 GB 空间。

4. pnpm 与 Native Addon

带有 C++ 原生编译绑定的包（如 sharp、bcrypt）在 pnpm 环境下有时会因为找不到头文件路径而编译失败：

# 临时关闭 strict-deps 解决 header 路径问题
pnpm install --strict-peer-dependencies=false

# 长期方案：在 package.json 中声明正确的 dependencies 层级

延伸阅读

• mac-dev-env-setup/homebrew-intro — 通过 Homebrew 安装 nvm
• mac-dev-env-setup/git-ssh-config — SSH 配置（用于 git clone private repos）
• mac-dev-env-setup/go-module-proxy — Go 生态的依赖管理对比参考