前端工程化 / 知识点

pnpm / npm 包管理速查手册

锁文件与版本固定

CODE
corepack use pnpm@<exact-version>; npm pkg set packageManager=<manager>@<exact-version>

通过 packageManager 字段统一团队和持续集成环境使用的工具版本。

固定包管理器版本

在仓库根目录用 packageManager 写明“工具名@精确版本”,再让 Corepack 或持续集成环境按该字段安装并校验。这样可以避免开发机与流水线因 pnpm/npm 版本不同而反复改写锁文件。

基本配置

pnpm 项目可在根 package.json 中固定版本:

json
{
  "name": "acme-app",
  "private": true,
  "packageManager": "pnpm@11.10.0"
}

npm 项目使用同一字段:

json
{
  "name": "acme-app",
  "private": true,
  "packageManager": "npm@11.19.0"
}

packageManager 应提交到版本库,并与对应锁文件一起评审。不要写 pnpm@^11 或 npm@latest;浮动范围会让不同时间执行安装时得到不同工具版本。

固定并验证 pnpm

在已有 package.json 的仓库根目录执行:

bash
set -e

# 当前 Node.js 环境没有 Corepack 时再安装,避免重复修改全局环境。
command -v corepack >/dev/null 2>&1 || npm install --global corepack@latest >/dev/null 2>&1

corepack enable pnpm
corepack use pnpm@11.10.0 >/dev/null 2>&1

printf 'declared=%s\nactual=pnpm@%s\n' \
  "$(node -p "require('./package.json').packageManager")" \
  "$(pnpm --version)"

预期输出:

text
declared=pnpm@11.10.0
actual=pnpm@11.10.0

corepack use 会更新根 package.json 的 packageManager。以后在该项目中调用 pnpm 时,应继续保留版本检查,确保 PATH 没有绕过 Corepack shim。

在持续集成中固定 npm

对于 npm,最直接的流水线做法是显式安装声明版本并断言结果。也可以在明确使用 Corepack 接管 npm 时执行 corepack enable npm。

bash
set -e

npm install --global npm@11.19.0 >/dev/null 2>&1
test "$(npm --version)" = "11.19.0"
printf 'npm@%s\n' "$(npm --version)"

预期输出:

text
npm@11.19.0

只写 packageManager 但不启用版本管理、安装指定 npm 或校验版本,并不会自动替换当前 PATH 中已经存在的工具。

风险与边界

  • 仅修改字段但未执行版本管理:旧的全局 pnpm/npm 仍可能被调用,后果是锁文件格式变化或安装结果不一致。安全做法是启用 Corepack,或在 CI 镜像中安装精确版本并执行版本断言。
  • 直接升级包管理器主版本:可能重写锁文件、改变依赖解析或脚本安全策略。应在独立分支升级,重新安装、测试并单独评审锁文件差异。
  • 在受限主机全局安装:可能因无写权限失败。优先使用预装好版本的 CI 镜像,或让 Corepack 在用户可写缓存目录中准备版本。

排障清单

  • corepack: command not found:安装 corepack@latest 后重试;不要假设所有 Node.js 安装方式都会附带 Corepack。
  • 声明版本与实际版本不一致:执行 command -v pnpm 或 command -v npm 检查 PATH 是否仍指向旧的全局二进制,再重新启用对应 shim。
  • 出现“项目配置为另一种包管理器”的错误:不要混用 npm 与 pnpm,按 packageManager 指定的工具重新执行安装。
  • CI 首次运行无法下载工具:为构建环境开放包注册表访问,或在镜像构建阶段预热并缓存指定版本。

速查:packageManager 负责声明,Corepack 或 CI 安装步骤负责兑现;两者缺一,版本就不算真正固定。

工作区与本地包

依赖解析与修复

仓库与发布环境

存储与安装排错

脚本与依赖审计

重装与回滚

目录与阅读设置

记录一个想法

pnpm / npm 包管理速查手册

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通