我很早就发现一个规律凡是直接复制粘贴 npm、pnpm、yarn 命令却没有先看运行环境的人大概率会在几个报错里反复绕圈——npm.ps1 无法加载、pnpm 不是内部或外部命令、certificate has expired、pnpm approve-builds。表面看这些都是“装不上”的玄学问题实际上是把三个层面搞混了依赖在 node_modules 里怎么放、命令本身从哪里来、下载走哪条网络通道。这篇文章不打算罗列一份“全网最全命令表”就完事我会把机制、安装环境、日常命令、高频报错放成一条线来讲。你看完以后遇到包管理器相关的问题能自己顺着报错往回推而不是再复制三份不同的命令碰运气。1. 三个工具对 node_modules 的差异决定了你该抄谁的命令1.1 npm 的依赖提升平坦但留下“幽灵依赖”npm 随 Node 一起分发是绝大多数人接触的第一个包管理器。但很多人不知道npm 的依赖布局并不是“天然合理”的。npm v2 时代是严格的嵌套结构每个依赖又各自维护自己的node_modules/xxx在网络差、依赖层级深的时候不仅安装极慢还会在 Windows 上触发“路径过长”问题。所以 npm v3 开始转向“依赖提升hoisting”安装时尽量把所有包平铺到根目录node_modules下只有遇到版本冲突才把冲突的子包嵌套到依赖它的包目录里。这个改动解决了性能问题却带来了三个长期被忽视的副作用。第一node_modules是“安装时结果”同一份 package.json 在不同时间、不同网络、不同顺序下安装最终提升到顶层的是谁可能不一样。第二代码里能require到某个包但它并没有出现在 package.json 里这就是社区常说的“幽灵依赖”。第三package-lock.json 能锁住版本号却锁不住依赖树里“顶层提升谁”的过程。很多从 npm 项目迁到 pnpm 的人会突然遇到Cannot find module并不是 pnpm 故意找茬而是旧代码在开发时就已经悄悄依赖了 npm 的宽松机制。读懂这一点后面很多报错就都有了答案。1.2 Yarn 的经典方案与 Yarn Berry 的激进转向Yarn Classic大家最常见的 yarn 1.x刚出来时的卖点不是“不同的 node_modules”而是确定性安装、离线缓存和并行下载。它解决的痛点很明确npm 当时在团队协作里经常出现“我这能跑你那跑不了”的问题yarn.lock 让依赖版本第一次真正做到全团队一致。所以你到现在还能看到大量老项目用 yarn 1锁文件一提交安装结果就很稳定。真正称得上“机制级变化”的是 Yarn Berryyarn 2它默认启用 PlugnPlayPnP项目里可以完全不生成 node_modules改用.pnp.cjs文件记录依赖映射依赖包以 zip 形式缓存在.yarn/cache。这种设计安装极快、依赖边界严格但门槛也很高很多编辑器、ESLint 插件、原生模块编译工具都需要针对 PnP 做适配过去“手动翻一下 node_modules 找东西”的操作习惯也全部失效。所以 Yarn Berry 推到今天在社区里仍然口碑两极分化不是它不先进而是它对你的工程习惯要求明显上了一个台阶。看到“yarn 比 npm 好”就盲目切换大概率会卡在配置期。1.3 pnpm 的存储基因硬链接、软链和严格依赖边界pnpm 把“机制”两个字体现得最明显。第一次安装包时pnpm 会把包解压进一个全局 storeMac/Linux 一般在~/.local/share/pnpm/storeWindows 上一般在%LOCALAPPDATA%\pnpm\store用pnpm store path可以查看具体位置。项目的node_modules并不是物理复制而是这样的结构项目根目录的node_modules下只保留直接依赖的符号链接真实文件统一放在node_modules/.pnpm/pkgversion/node_modules/pkg下再通过硬链接指向全局 store 里的物理文件每个包在.pnpm/pkgversion/node_modules/下只能看到自己声明过的依赖越权 require 别的包会直接失败。这套设计带来了三个好处多项目磁盘占用断崖式下降安装速度因为大量硬链接避免了解压复制而明显变快幽灵依赖被从根本上拦住。代价同样存在硬链接不能跨文件系统如果 global store 和项目在不同盘符会退化成复制速度和磁盘收益都会打折。另外 pnpm 对依赖的 postinstall 脚本默认不自动执行esbuild、sharp 这类需要编译或下载二进制的包就会被挡住这也就是后来那句Run pnpm approve-builds to pick which dependencies should be allowed to run的由来。1.4 机制差异汇总表维度npmYarn Classicpnpm依赖布局扁平提升层级不固定扁平提升但确定性更强符号链接 硬链接严格隔离幽灵依赖存在存在基本杜绝锁文件package-lock.jsonyarn.lockpnpm-lock.yaml默认是否运行依赖 postinstall 脚本允许允许默认阻止需 approve-builds多项目磁盘复用无无全局 store 复用适合场景默认选择兼容性最好老项目稳定维护大型仓库、Monorepo、磁盘敏感环境做完这层对比你再看热词里那些“npm 安装”“pnpm 下载失败”“yarn 管理”的问题会发现大部分都不是工具本身坏了而是机制预期不同。先选对工具再谈命令。2. 安装、PATH、registry命令“找不到”比“报错”更常见2.1 用 npm 还是 corepack 安装 pnpm 和 yarn最常见的安装方式就两条npm install -g pnpm npm install -g yarn但我更推荐在 Node 16.9 上使用自带的 corepackcorepack enable corepack prepare pnpmlatest --activatecorepack 的好处是可以按项目锁定包管理器版本。团队里有人用 pnpm 7、有人用 pnpm 10这种混乱很容易让同一条pnpm install在制造不同格式的 lockfile。用 corepack 配合packageManager字段能在项目层面实现统一{ packageManager: pnpm10.0.0 }热词里大量出现的“pnpm 下载失败”其实分很多种网络层失败、registry 源不通、磁盘缓存损坏、版本不存在。“失败后不要疯狂重试”先看清报错文本属于哪一层。网络层就换源或检查代理设置证书层就按第五章的链路排查下载一半失败就清缓存重试。不看报错反复安装很容易把临时故障固化成环境问题。2.2 终端不认识命令时先查 PATH 而不是重装这个问题在 Windows 上尤其常见你明明执行了npm install -g pnpm安装过程也没报错但新开一个终端输入pnpm -v系统却回一句“pnpm 不是内部或外部命令也不是可运行的程序或批处理文件”。原因很简单npm 的全局 bin 目录没在 PATH 环境变量里。排查链路如下第一步确认包确实装上了。npm ls -g --depth0能看到pnpm或yarn说明安装成功问题不在安装本身。第二步拿到 npm 全局目录位置。npm config get prefixWindows 下常见的结果是C:\Users\你的用户名\AppData\Roaming\npm你到那个目录下能看到pnpm.cmd或pnpm.ps1。第三步把这个目录加到用户 PATH 里然后重开终端。macOS 和 Linux 上用which pnpm如果输出空检查~/.zshrc或~/.bashrc里是否包含 npm 全局 bin 路径。还有个隐蔽坑如果用了 nvm 或 fnm 这类 Node 版本管理工具全局包是装在“当前 Node 版本”对应的路径下的。切换 Node 版本后全局命令可能瞬间消失。这不是包被卸载了是路径切换了。要么固定默认 Node 版本要么每个版本都重新装一次全局工具别在版本切换后还指望命令能在原地等着你。2.3 PowerShell 的“禁止运行脚本”到底卡在哪npm : 无法加载文件 C:\Program Files\nodejs\npm.ps1因为在此系统上禁止运行脚本。这可以说是 Windows 本地开发最经典的问题。看到这句话先要明白它跟 Node 没关系它是 PowerShell 执行策略拦截了.ps1脚本。npm 在 PowerShell 里会调用npm.ps1而 Windows 客户端默认的执行策略是 Restricted本地脚本一律不允许运行。解决方法是用管理员或当前用户身份放开一个比较安全的策略Get-ExecutionPolicy -List Set-ExecutionPolicy -Scope CurrentUser RemoteSignedRemoteSigned的意思是本地脚本没有签名也可以运行从网上下载的脚本必须带可信签名。日常开发够用了不要图省事直接设成Unrestricted那是把所有下载脚本都放行等于把供应链风险敞口开大。如果你在公司电脑上遇到 LocalMachine 策略被组织策略锁死别去硬改直接用 cmd 或 Windows Terminal 里的 Command Prompt 跑 npm绕开 PowerShell 执行策略即可。这种场景下你需要的不是“解锁”而是“绕行”。2.4 registry 镜像源的配置边界与旧域名陷阱热词里那条npm ERR! code cert_has_expired很有代表性它指向的请求地址是https://registry.npm.taobao.org/...。这个老域名已经停止维护了TLS 证书过期但很多人当年的全局.npmrc里还一直留着它。三个工具其实都会读.npmrc配置字段也基本一致。查看方式npm config get registry pnpm config get registry yarn config get registry如果没有特殊原因官方源npm config set registry https://registry.npmjs.org/需要国内加速用新的 npmmirror 域名不是旧 taobaonpm config set registry https://registry.npmmirror.com/.npmrc的优先级是项目本地.npmrc 用户目录.npmrc 全局.npmrc。所以项目里的.npmrc写错了用户级配置是覆盖不了它的。我在帮别人排查时经常发现明明改好了全局配置跑项目还报旧源错误最后一看是项目根目录的.npmrc里残留了registryhttps://registry.npm.taobao.org。求你检查到这一层再动手重装。另外提醒一点strict-sslfalse只能是临时调试手段别把它写进配置里长期使用。关闭证书校验等于把所有依赖包的完整性都交给网络链路一旦中间被改动你根本察觉不到。3. 命令地图高频操作对照与迁移注意事项3.1 日常高频命令对照表下面这张表覆盖了平时 90% 的操作建议直接收藏操作npmpnpmYarn Classic安装项目全部依赖npm installpnpm installyarn或yarn install添加 dependenciesnpm install pkgpnpm add pkgyarn add pkg添加 devDependenciesnpm install -D pkgpnpm add -D pkgyarn add -D pkg移除依赖npm uninstall pkgpnpm remove pkgyarn remove pkg更新依赖版本npm update pkgpnpm update pkgyarn upgrade pkg运行脚本npm run xxxpnpm run xxx或pnpm xxxyarn run xxx或yarn xxx全局安装npm install -g pkgpnpm add -g pkgyarn global add pkg一次性执行工具包npx pkgpnpm dlx pkgyarn dlx pkgYarn 2查看全局 bin 目录npm prefix -gpnpm bin -gyarn global bin清理缓存npm cache clean --forcepnpm store pruneyarn cache clean很多人第一次用 pnpm容易把pnpm add -g记成pnpm install -g。如果你用pnpm install -g pkgpnpm 会把它当成“当前项目全局安装目录下的指令”行为跟 npm 完全不同。这也是为什么我一直强调“抄命令之前先看机制”——npm 的install和 pnpm 的install根本不是同一个语义。3.2 从 npm/yarn 迁移到 pnpm 时要做的几件事团队切到 pnpm 不是改一个命令就完事我建议按这个顺序走先确保当前 git 工作区干净提交一次“迁移前备份”。这样中间出问题可以随时回滚。删除旧的 lockfile 和 node_modulesrm -rf node_modules package-lock.json yarn.lock如果希望尽量复用旧 lockfile 里的解析结果先执行pnpm import它会根据旧的 package-lock.json 或 yarn.lock 生成 pnpm-lock.yaml。不执行也可以直接让 pnpm 重新解析。执行pnpm install注意观察输出里有没有Ignored build scripts。如果出现被忽略的构建脚本运行pnpm approve-builds或者把允许名单直接写进 package.json{ pnpm: { onlyBuiltDependencies: [esbuild, sharp] } }检查项目根目录.npmrc里有没有shamefully-hoisttrue。这个配置会让 pnpm 临时复刻 npm 的扁平 node_modules如果你有某个旧库必须访问幽灵依赖只能靠它兼容。但这不是长期方案迁移完成后应该逐步修掉那些越权依赖。为什么我把“commit 一次备份”放在第一因为迁移最大的风险不是命令不对而是你在无回滚点的情况下把项目越改越乱最后连“改了什么”都说不清。3.3 同名命令在不同工具里的“语义差”表格里能看出命令名不一样但更坑的是那些“命令名一样、语义不一样”的角落。npm link和pnpm link都用于本地包联调但默认行为有差异。npm 的npm link会把全局包链到项目里也可能把当前项目链到全局具体看你执行位置pnpm 则更强调显式参数建议直接写pnpm link --global。我在 monorepo 里做本地联调时最稳的做法是用 workspace protocol而不是裸用 link。yarn裸命令等价于yarn install但npm裸命令只是打印帮助信息并不执行安装。很多从 yarn 转 npm 的新人习惯性在终端敲一个npm然后奇怪为什么没有装依赖——这不是 bug是设计差异。npx、pnpm dlx、yarn dlx三个都用于临时执行工具包但执行完之后的缓存策略不同。npx在旧版本里会留下很多临时包pnpm dlx用 store 缓存比较克制。在 CI 里临时执行一个 CLI 工具我更喜欢pnpm dlx因为它不往项目目录里塞东西。4. 高频报错排查链路从报错文本反推机制4.1 链路Anpm.ps1 无法运行脚本报错文本前面已经贴过一遍这里讲完整的排查思路。第一确认执行策略Get-ExecutionPolicy -List如果输出里CurrentUser或LocalMachine对应的是Restricted这就是报错根源。第二修正当前用户策略Set-ExecutionPolicy -Scope CurrentUser RemoteSigned第三重开终端验证npm -v。这个链路里最常见的误区是去重装 Node。重装并不会改 PowerShell 执行策略所以什么用都没有。还有一个误区是把策略设成Unrestricted解决了一时但给以后埋雷我前面已经说过原因。如果你处于公司策略管制的机器上RemoteSigned也可能被组策略覆盖这时候要么联系管理员开放要么直接用 cmd 执行 npm。4.2 链路B“不是内部或外部命令”的三种藏身处这个报错在 Windows 上有三个常见藏身处按出现概率排序。第一处是 PATH 缺 npm 全局目录。处理方式见 2.2核心是npm config get prefix拿到目录把它加进用户 PATH。第二处是 Node 版本管理器切换后全局路径失效。用where pnpm看一下有没有命中命中为空就说明当前 Node 版本下没有安装对应全局包。解决方法是给默认版本重装或者直接用 corepack。第三处是安装过程被安全软件拦截导致.cmd文件根本没生成。在npm config get prefix返回的目录下看有没有pnpm.cmd没看到就检查杀毒软件隔离区。这几年 Windows 上某些安全软件会把 pnpm 的 shim 误判为可疑文件这个坑比想象中常见。4.3 链路Ccert_has_expired 与旧淘宝源迁移报错样本npm ERR! code cert_has_expired npm ERR! request to https://registry.npm.taobao.org/vuex-along/download/vuex-along-1.2.11.tgz failed, reason: certificate has expired从报错文本里可以直接看到registry.npm.taobao.org这就是问题入口。处理分三步修改 registrynpm config set registry https://registry.npmmirror.com清理可能存在的缓存npm cache clean --force重装依赖或重试命令。还有一些边界情况。系统时间不对也会导致证书校验失败这个在老旧机器或虚拟机里见过很多次。先把系统时间同步“自动设置”再去追究证书问题。另外如果项目级.npmrc里写死了旧域名就算用户级配置改好了也会被覆盖所以排查一定要先看项目根目录的.npmrc。4.4 链路Dpnpm 阻断构建脚本approve-builds 怎么用pnpm 安装完成时输出Ignored build scripts: esbuild, sharp Run pnpm approve-builds to pick which dependencies should be allowed to run.这是 pnpm 的安全机制依赖包声明的 postinstall 脚本默认不会被执行。原因很实际依赖安装阶段执行任意脚本是供应链攻击的高发场景npm 时代很多恶意包就是靠 postinstall 在开发者机器上跑代码。pnpm 选择了默认阻断要求你显式授权。两种放行方式方式一交互式pnpm approve-builds然后按提示勾选需要放行的依赖。方式二写配置自动放行{ pnpm: { onlyBuiltDependencies: [esbuild, sharp] } }如果安装完之后又改了配置想重新触发构建脚本可以执行pnpm rebuild有个反面操作也要提醒有人嫌 approve-builds 烦直接在.npmrc里写ignore-scriptstrue。这个配置会把所有依赖脚本全部禁掉esbuild、sharp 这类包安装后直接缺二进制文件运行时才报错排查起来更痛苦。安全机制是用来配合的不是用来绕的。5. 锁文件与 CI 场景团队协作不要“三锁并存”5.1 lockfile每个工具都有自己的“走向记录”package-lock.json、yarn.lock、pnpm-lock.yaml 虽然是不同格式但核心目标一致记录依赖解析的最终版本和来源让所有人安装出同一棵树。lockfile 必须提交到 git否则团队协作就是碰运气。比“不提交 lockfile”更糟的是“同时提交多份 lockfile”。如果一个仓库里既能看到 package-lock.json又能看到 yarn.lock 或 pnpm-lock.yaml说明有人混用了不同工具。这会让 CI 反复生成不同的依赖树轻则安装缓慢重则出现只在某一台机器上能跑的 bug。我参与过很多次这种清理处理办法很简单团队约定只保留一个工具删除其他 lockfile在 README 里写明“统一使用 pnpm”。如果历史包袱太重至少要在 CI 入口加一个检查发现多余 lockfile 直接报错让混用问题在早期暴露。5.2 CI 环境里最稳的三种安装姿势工具CI 推荐命令npmnpm cipnpmpnpm install --frozen-lockfileYarn Classicyarn install --frozen-lockfile为什么 npm 要专门出一个npm ci因为它会先删除 node_modules再严格按照 package-lock.json 安装并且不会修改 lockfile。普通npm install在依赖版本漂移时可能会悄悄更新 lockfile这在 CI 里是不可接受的因为你不知道这次构建到底装了什么。pnpm 的对应参数是--frozen-lockfile锁文件与 package.json 不一致时直接失败绝不会自动改锁文件。团队里如果有人在本地用pnpm install跑出了新版本 lockfileCI 会第一时间报警这是好行为不是故障。还想提一个 CI 细节缓存 pnpm 的全局 store 能显著提速。不同 CI 平台的缓存目录不一致先执行pnpm store path拿到路径再配置到 CI 缓存里。缓存失效时先清空 store 再跑pnpm install不要直接怀疑网络或依赖本身有问题。5.3 用完 pnpm workspace 之后命令往往会多一层大型前端仓库普遍会升级到 monorepo 结构pnpm 在这个场景下优势更明显。workspace 通过根目录pnpm-workspace.yaml声明packages: - packages/*子包之间的相互依赖可以直接用 workspace 协议{ dependencies: { app/shared: workspace:* } }批量操作命令pnpm -r install pnpm -F app/server dev-r表示递归执行-F表示过滤到某个具体子包。npm 和 yarn 也有类似能力但 pnpm 对 workspace 的依赖隔离做得更彻底。如果你在 monorepo 里曾经被“子包之间互相乱引用”折磨过切换到 pnpm 会很有体感。最后再分享几个我实际踩过的经验第一个经验切换包管理器之前先提交一次干净的 git 状态再多旧项目都别跳过这一步。中间想回滚随时能回心里不慌排查问题也敢放开手脚。第二个经验报错文本本身就是最精准的线索。cert_has_expired指向证书和源not recognized as an internal or external command指向 PATHIgnored build scripts指向 pnpm 安全策略。不要只把报错复制进搜索引擎先看它属于哪一层网络层、环境层、依赖层还是安全策略层。层判断对了问题基本已经解决一半。第三个经验顺手的工程化习惯是“锁定包管理器版本”。无论是 corepack 的packageManager字段还是 CI 里的--frozen-lockfile本质都是把不确定性挡在外面。依赖管理和包管理器版本这两件事都应该追求“确定”。确定才能复现复现才能排错。