npm 与 pnpm 安装的到底是什么？从 JavaScript 包到原生模块

npm、pnpm、Node.js 和 nvm 分别是什么#

• Node.js 是 JavaScript 的运行时，负责执行 JavaScript 程序。
• npm 是 Node.js 生态的包管理器，通常随 Node.js 一起安装。它负责下载依赖、维护 package.json 和 package-lock.json，也能执行项目脚本。
• pnpm 是独立的 Node.js 包管理器。它与 npm 使用同一个 npm registry 生态，但命令、锁文件和 node_modules 的组织方式有所不同。
• nvm 是 Node.js 版本管理器，用来安装和切换 Node.js 版本。它不是包管理器，也不负责安装项目依赖。
• Corepack 是包管理器入口和版本准备工具。它可以根据项目声明准备指定版本的 pnpm 或 Yarn，但它不是 npm，也不负责安装项目依赖。

在 WSL2 中准备 Node.js#

进入 Ubuntu 后，可以先确认系统和 shell。以下输出只保留与教程有关的部分：

1
user@wsl:~$ uname -sr
2
Linux 6.x.x-microsoft-standard-WSL2
3
user@wsl:~$ bash --version | head -n 1
4
GNU bash, version 5.1.16

使用 nvm 安装 Node.js。安装远程脚本前应先阅读来源和内容，因为 curl | bash 会直接执行下载的脚本：

1
user@wsl:~$ curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.7/install.sh | bash
2
=> Downloading nvm from git to '$HOME/.nvm'
3
=> Appending nvm source string to '$HOME/.bashrc'

当前 shell 立即加载 nvm：

1
user@wsl:~$ . "$HOME/.nvm/nvm.sh"
2
user@wsl:~$ nvm install 24
3
Downloading and installing node v24.20.0...
4
Computing checksum with sha256sum
5
Checksums matched!
6
Now using node v24.20.0 (npm v11.19.0)
7
Creating default alias: default -> 24 (-> v24.20.0 *)
8
user@wsl:~$ node --version
9
v24.20.0
10
user@wsl:~$ npm --version
11
11.19.0

这里的 npm 已经随 Node.js 一起提供。此时可以使用 npm，但还没有因为安装 Node.js 就自动得到 pnpm。

Corepack 到底做什么#

Corepack 最容易被误解成“另一个包管理器”。更准确的分层是：

1. Node.js 执行 JavaScript。
2. npm 是一个包管理器，通常随 Node.js 分发。
3. pnpm 和 Yarn 是其他包管理器。
4. Corepack 是包管理器版本管理器，为 pnpm、Yarn 等准备版本并提供转发入口。

Corepack 解决的问题是：应该运行哪个版本的包管理器。它不解决：项目应该安装哪些依赖。后一个问题仍由 pnpm install、pnpm add、npm install 等命令负责。

这里有一个容易随 Node.js 版本变化的现实：不能假设每个 Node.js 发行版都内置 Corepack。检查命令是否存在；如果不存在，按项目文档安装 pnpm，或者使用 pnpm 官方提供的安装方式。无论采用哪种方式，最后都要检查实际运行的 pnpm --version，而不是只检查安装命令是否成功。

1
user@wsl:~$ corepack --version
2
0.35.0
3
user@wsl:~$ corepack enable pnpm
4
user@wsl:~$ type -a pnpm
5
pnpm is .../bin/pnpm

1
user@wsl:~$ pnpm --version
2
! Corepack is about to download https://registry.npmjs.org/pnpm/-/pnpm-11.24.0.tgz
3
? Do you want to continue? [Y/n] y
4
11.24.0

1
"packageManager": "pnpm@11.22.0"

1
manage-package-manager-versions = true

1
user@wsl:~$ node --version
2
v24.20.0
3
user@wsl:~$ npm --version
4
11.19.0
5
user@wsl:~$ corepack --version
6
0.35.0
7
user@wsl:~$ pnpm --version
8
11.24.0

用隔离项目观察安装过程#

不要为了学习包管理器直接修改重要项目。创建临时目录后，在其中安装几个形态不同的包：

1
user@wsl:~$ tmp_dir=$(mktemp -d)
2
user@wsl:~$ echo "$tmp_dir"
3
/tmp/tmp.xxxxxxxx
4
user@wsl:~$ cd "$tmp_dir"
5
user@wsl:/tmp/tmp.xxxxxxxx$ pnpm init
6
Wrote to /tmp/tmp.xxxxxxxx/package.json
7
user@wsl:/tmp/tmp.xxxxxxxx$ pnpm add lodash typescript sharp
8
Packages: +9
9
Progress: resolved 54, reused 0, downloaded 12, added 9, done
10

11
 dependencies:
12
+ lodash 4.18.1
13
+ sharp 0.35.4
14
+ typescript 7.0.2
15

16
Done in 6.5s using pnpm v11.24.0

这里的版本和下载数量会变化。重要的是动作：pnpm init 创建 package.json，pnpm add 修改依赖声明、解析依赖并创建安装目录。

查看生成的声明：

1
user@wsl:/tmp/tmp.xxxxxxxx$ cat package.json
2
{
3
  "name": "tmp-project",
4
  "version": "1.0.0",
5
  "packageManager": "pnpm@11.24.0",
6
  "type": "module",
7
  "dependencies": {
8
    "lodash": "^4.18.1",
9
    "sharp": "^0.35.4",
10
    "typescript": "^7.0.2"
11
  }
12
}

pnpm init 在不同版本中生成的字段可能不同。不要把临时项目的名字、版本或格式当成固定模板。

1
user@wsl:~$ npm_dir=$(mktemp -d)
2
user@wsl:~$ cd "$npm_dir"
3
user@wsl:/tmp/tmp.yyyyyyyy$ npm init -y
4
Wrote to /tmp/tmp.yyyyyyyy/package.json
5
user@wsl:/tmp/tmp.yyyyyyyy$ npm install --save-dev typescript
6
added 1 package, and audited 2 packages in 1s
7
user@wsl:/tmp/tmp.yyyyyyyy$ npm exec tsc -- --version
8
Version 7.0.2

包不是语言#

registry 发布的是带元数据的 tarball，而不是“一个 JavaScript 文件”。包中可以包含：

• JavaScript 或 TypeScript 源码
• WASM 文件
• 原生 .node 模块
• 预编译二进制
• CLI 入口
• 其他包的运行时或平台依赖

实验中的三个包分别说明了不同情况：

• lodash 主要作为可导入的 JavaScript API 使用。
• typescript 提供 API，也通过 bin 字段提供 tsc 命令。
• sharp 会根据操作系统和 CPU 解析平台相关实现，安装时可能出现 @img/* 等平台包。

查询 registry 元数据：

1
user@wsl:/tmp/tmp.xxxxxxxx$ pnpm view lodash dist.tarball
2
https://registry.npmjs.org/lodash/-/lodash-4.18.1.tgz
3
user@wsl:/tmp/tmp.xxxxxxxx$ pnpm view typescript bin --json
4
{
5
  "tsc": "bin/tsc"
6
}

bin 字段表示包声明了命令入口。安装后，包管理器会在项目中创建 node_modules/.bin/tsc 的链接或 shim：

1
user@wsl:/tmp/tmp.xxxxxxxx$ pnpm exec tsc --version
2
Version 7.0.2

tsc 不是 shell 自带命令，也不是独立安装的系统程序。它来自 TypeScript 包的 bin 声明，最终由 Node.js 执行。判断一个包能做什么，应查看它的 exports、main、bin、平台依赖和安装脚本，而不是只看包名。

一次安装改变了哪些东西#

可以把项目依赖分成三层：

1. 声明层：package.json 中的 dependencies 和 devDependencies。
2. 解析层：lockfile 中的实际版本、间接依赖、peer dependency 和完整性信息。
3. 落盘层：store、virtual store、node_modules 链接和 .bin 入口。

运行 pnpm add lodash 时，大致发生四步：

1. 读取项目边界和 registry 配置。
2. 查询包元数据，按照 semver 范围选择版本并写入 lockfile。
3. 下载 tarball，校验后写入内容寻址 store。
4. 在项目中创建依赖链接和命令入口。

用命令查看这些层：

1
user@wsl:/tmp/tmp.xxxxxxxx$ pnpm root
2
/tmp/tmp.xxxxxxxx/node_modules
3
user@wsl:/tmp/tmp.xxxxxxxx$ pnpm store path
4
<home-directory>/.local/share/pnpm/store/v11
5
user@wsl:/tmp/tmp.xxxxxxxx$ realpath node_modules/lodash
6
/tmp/tmp.xxxxxxxx/node_modules/.pnpm/lodash@4.18.1/node_modules/lodash
7
user@wsl:/tmp/tmp.xxxxxxxx$ pnpm why sharp
8
sharp@0.35.4
9
└── tmp-project@1.0.0 (dependencies)

pnpm 的 store 像共享零件仓，node_modules/.pnpm 像当前项目的装配区，顶层 node_modules/lodash 是给 Node.js 看的入口。多个项目可以复用 store，但项目自己的 package.json、lockfile、链接和 peer 组合仍然独立。

npm 的目标相同，但默认的依赖布局不同。应用代码应依赖包公开的 exports 或 main，不要依赖某个包管理器偶然生成的内部路径。

^1.2.3 是版本范围，不是唯一版本。它允许一定范围内的更新；lockfile 则记录这次实际选择的版本。pnpm install --frozen-lockfile 会拒绝在安装时偷偷修改 lockfile，适合 CI 和新机器：

1
user@wsl:/path/to/project$ pnpm install --frozen-lockfile
2
Lockfile is up to date, resolution step is skipped
3
Already up to date

npm 项目通常使用 npm ci 达到类似的“按已有锁文件安装”效果。pnpm install 和 pnpm update 也不是一回事：前者按当前声明安装，后者主动寻找允许范围内的新版本。

命令为什么能运行#

普通 shell 通过 PATH 查找命令：

1
user@wsl:/tmp/tmp.xxxxxxxx$ command -v node
2
<node-installation>/bin/node
3
user@wsl:/tmp/tmp.xxxxxxxx$ type -a pnpm
4
pnpm is <node-installation>/bin/pnpm

执行项目脚本时，npm 和 pnpm 会临时把项目的 node_modules/.bin 放到脚本环境的 PATH 前面。因此，安装 TypeScript 后可以在 package.json 中定义：

1
"scripts": {
2
  "type-check": "tsc --version"
3
}

普通 shell 不会自动注入这层 PATH。可以通过以下两种入口明确执行同一个本地 tsc：

1
user@wsl:/path/to/project$ pnpm exec tsc --version
2
Version 7.0.2
3
user@wsl:/path/to/project$ node_modules/.bin/tsc --version
4
Version 7.0.2

四种常见入口可以这样区分：

1. node src/index.mjs：Node.js 直接运行文件。
2. pnpm exec tsc --version：从当前项目依赖中寻找并运行 tsc。
3. pnpm run dev：读取 package.json 的 scripts，并注入本地 .bin PATH。
4. 脚本启动 Node.js、shell 或其他子进程：子进程继承脚本环境。

registry、换源和网络故障#

registry 是提供包元数据和 tarball 的 HTTP 服务。它可以是 npm 默认 registry、第三方镜像、公司私有 registry 或代理缓存。切换 registry 只改变查询和下载的来源，不改变项目依赖目录，也不会自动修复错误的版本范围。

我会先检查当前配置，而不是直接删除缓存：

1
user@wsl:/tmp/tmp.xxxxxxxx$ pnpm config get registry
2
https://registry.npmjs.org/
3
user@wsl:/tmp/tmp.xxxxxxxx$ npm config get registry
4
https://registry.npmjs.org/

只验证一次时，使用命令行参数，不改变配置文件：

1
user@wsl:/tmp/tmp.xxxxxxxx$ pnpm view lodash version --registry=https://registry.npmjs.org/
2
4.18.1

项目级 .npmrc 适合项目配置，用户级配置适合个人默认值。认证信息不要写死在仓库中：

1
//registry.example.invalid/:_authToken=${NPM_TOKEN}

遇到 ERR_PNPM_NO_MATCHING_VERSION，先检查包名、registry 和可用版本，再检查 semver、lockfile 和平台限制。遇到网络超时或证书错误，依次检查 registry、DNS、代理、系统时间和 CA。不要把清空整个缓存当成万能修复。

audit 与生命周期脚本#

audit 会把依赖树中的包名和版本与已知漏洞公告进行匹配。它不审查业务代码，也不能证明没有报告的包绝对安全：

1
user@wsl:/tmp/tmp.xxxxxxxx$ pnpm audit
2
No known vulnerabilities found
3
user@wsl:/tmp/tmp.xxxxxxxx$ pnpm audit --prod
4
No known vulnerabilities found

安装依赖本身也可能执行代码。preinstall、install、postinstall 和 prepare 可能编译 native addon、下载平台产物、生成代码，甚至执行任意脚本。安装前应审查包来源和生命周期脚本；在 CI 中可以评估 --ignore-scripts 是否适合项目，但不要把关闭安全检查当成第一步修复。

如果项目的 package.json 声明了 devEngines.packageManager，却使用了错误的包管理器，npm 可能报：

1
npm error code EBADDEVENGINES
2
npm error Invalid name "pnpm" does not match "npm"

这表示当前 npm 不符合项目要求，不是一次漏洞扫描结果。正确做法是切换到项目声明的 pnpm，而不是删除检查或绕过它。

从零建立可迁移环境#

新机器可以按以下顺序操作：

1. 在 WSL2 中准备 Ubuntu 和 shell。
2. 使用 nvm 安装满足项目 engines 的 Node.js，并确认 shell 启动文件已加载 nvm。
3. 检查 node --version 和 npm --version。
4. 启用或安装项目规定的 pnpm，并检查 corepack --version（若存在）和 pnpm --version。
5. 进入项目根目录，先阅读 package.json 的 packageManager、engines 和 lockfile 类型。
6. 执行项目规定的锁定安装：pnpm 项目使用 pnpm install --frozen-lockfile，npm 项目通常使用 npm ci。
7. 按项目文档执行开发、检查、构建和预览命令。

如果项目位于 /mnt/c 或其他 Windows 挂载路径，安装和大量小文件访问可能明显慢于 Linux 文件系统中的 ~/projects。这是 I/O 边界的代价，不是 pnpm store 损坏；我通常把源码和 store 放在 WSL2 的 Linux 文件系统里，只通过编辑器或 Git 与 Windows 侧协作。

最小排错表：

整条路径可以概括为：

真正值得记住的不是一串安装咒语，而是这条边界链：包从哪个 registry 来，版本解析记录在哪里，文件落在哪一层，命令由哪个入口转给哪个 Node.js。顺着这条链排查，npm 和 pnpm 的差异就会变成可以观察和验证的实现选择。未来包管理器大概还会继续把“下载一个包”包装成更多自动化，但 lockfile、脚本和运行时边界不会凭空消失；理解它们，至少能让下一次 command not found 变成一个可定位的实验，而不是一次祈祷。

参考资料#

• npm package.json 文档
• npm scripts 文档
• npm audit 文档
• pnpm add 文档
• pnpm package.json 文档
• pnpm store 文档
• pnpm Node-Modules 设置
• Node.js Corepack 文档
• Node.js npm 入门指南