企业官网建设流程全解析

网上关于 npm、pnpm、yarn 的命令对照表可谓一抓一大把，但绝大多数只是把命令罗列在一起，根本没讲清楚一个问题：同一个命令，为什么在这三个工具里行为不一样？为什么 npm 装完能直接用、pnpm 装完可能报 ERESOLVE，yarn 装完又会生成一个莫名其妙带 .yarn 的目录？我见过不少同学拿着 yarn.lock 当 package-lock.json 用，也见过有人把 pnpm 的符号链接结构当成“装坏了”直接删掉重来。这篇内容我不想再给你一份“命令大全”，而是把三个包管理器背后的设计逻辑拆开，再给一版可以直接抄的命令地图，最后把搜索引擎里高频出现的报错集中做一轮排查复盘。适合正在从 npm 迁移到 pnpm、或者被 yarn 经典版和 Berry 版本搞晕的开发者，也适合刚入门前端工程化、想知道“为什么这么装”的新人。

1. 机制先讲明白：同一份命令，三个工具为什么行为大不同

1.1 npm：扁平化 node_modules 带来的历史包袱与幽灵依赖

npm 从 v3 开始把依赖安装策略从“嵌套结构”改成了默认“扁平化提升”。早期 npm 安装依赖是递归的，A 依赖 B、B 依赖 C，node_modules 里就会一层套一层，路径极深，Windows 上文件路径过长直接报错。v3 之后，npm 会把所有依赖尽量提升到顶层 node_modules 里，也就是“扁平化”。

这套方案解决了路径过长的问题，代价是“不确定性”。举个例子：项目里同时有 A 依赖 C@1、B 依赖 C@2，npm 安装时只能提升其中一个到顶层，另一个被嵌套在子目录里。至于哪一级被提升、哪一级被嵌套，取决于安装顺序和依赖树解析顺序。这也就是为什么 npm v5 之前，同一个 package.json 在不同机器上执行 npm install 可能得到两份完全不一样的 node_modules。npm v5 引入 package-lock.json 锁文件，才把依赖树固定下来，真正解决了“我本地能跑，你那边装完就挂”的经典问题。

但扁平化还带来一个隐患，叫“幽灵依赖”。项目里明明没直接声明某个包，但因为另一个依赖把这个包提升到了顶层 node_modules，你的代码就能直接 require/import 到它。开发时一切正常，等你发布到生产环境或者换了包管理器，幽灵依赖消失，代码瞬间崩溃。这类问题排查起来极其痛苦，因为报错信息通常只说“Cannot find module xxx”，不会告诉你来源。如果你长期用 npm，我强烈建议在 ESLint 里开 import/no-extraneous-dependencies 或者装一个 check-dependency-cruiser 这类工具，专门抓这种未声明的依赖引用。

1.2 yarn 1.x：缓存先行，但底层仍是扁平化逻辑

yarn 经典版（1.x）是 Facebook 在 2016 年推出的，核心卖点是“快”：并行下载、全局缓存、离线安装模式。它的 yarn.lock 锁文件在设计上确实比 package-lock.json 更早也更好读，因此迅速吸引了大量团队切换。不过 yarn 1.x 在 node_modules 结构算法上依然是 npm 那套“扁提升”，幽灵依赖问题一个都不少。

更要命的是，yarn 后来推出了 2.x/3.x/4.x，也就是 Berry 系列。Berry 彻底重写引擎，还引入了 Plug'n'Play（PnP）模式，把依赖打包成 .zip 文件存放在缓存里，通过 .pnp.cjs 映射表解析，根本不再生成 node_modules 目录。好处是安装极快、磁盘占用极低、依赖隔离更严格，坏处是兼容性容易出问题——很多原生模块、Electron 构建、老工具链对 PnP 都支持得不好。于是 Berry 又提供了 node-modules 模式作为兼容回退。这就造成了一个很分裂的现状：网上搜 yarn 命令，一半是 yarn 1.x 的，一半是 Berry 的。你说 yarn add 一个包，1.x 和 Berry 语义大体一致，但yarn global add在 Berry 里直接被移除，换成yarn dlx，而很多旧教程还在教yarn global add http-server。这大概是我见过初学者最容易栽的坑之一。看到项目目录里没有 node_modules、而是多了一个 .pnp.cjs 文件，别慌，这是 Berry 在正常工作。

1.3 pnpm：符号链接 + 硬链接的内容寻址存储，到底在解决什么问题

pnpm 和前面两个工具最本质的区别，是它不搞“复制文件到项目里”那套逻辑，而是用了“全局 store + 硬链接 + 符号链接”的组合方案。

第一次执行 pnpm install 时，依赖包被下载并解压到一个统一的全局 store 目录里，然后项目里的 node_modules 通过硬链接指向 store 中的文件。如果同一个版本的包在十个项目里都要用，磁盘上只保存一份物理文件，其余全是硬链接。这就是为什么 pnpm 的磁盘占用远比 npm/yarn 低。项目的子依赖结构也完全不同：pnpm 会在 node_modules/.pnpm 目录下真正存放依赖的内容，然后在顶层 node_modules 里只放一层符号链接，指向 .pnpm 里对应的包目录。这种设计让项目的 node_modules 变成“严格依赖隔离”结构：你只能 import 到 package.json 里显式声明的依赖，幽灵依赖从根本上被掐死。

当然 pnpm 也不是没有成本。有些工具对符号链接处理不友好，比如某些打包器、Electron、node-gyp 编译原生模块时，可能找不到真实路径。好在 pnpm 官方提供了node-linker=hoisted和node-linker=pnp等选项来适配不同场景。2025 年 pnpm v10 发布后，默认进一步收紧依赖构建脚本的权限，安装时不会再自动运行依赖的 postinstall 脚本，而是提示开发者手动执行pnpm approve-builds选择信任哪些依赖。这个改动让安全性大幅提升，但也让很多不了解机制的人一头雾水——安装完依赖后突然看到一条 “Ignored build scripts: esbuild”，以为安装失败了，其实是 pnpm 在刻意拦截。这里我多说一句：pnpm v10 的拦截其实是“白名单机制”，你运行pnpm approve-builds后，它会进入交互式界面，列出哪些依赖声明了 build 脚本，问你要不要放行。如果依赖里含有 esbuild、node-sass、sharp 这类必须执行 postinstall 才能正常工作的包，就逐个按 a 加入白名单，最后回车确认。嫌交互麻烦，也可以在 package.json 里手动声明：

{ "pnpm": { "onlyBuiltDependencies": ["esbuild", "sharp"] } }

这样下次安装就直接放行，不用再走审批流程。

1.4 概念澄清：前端包的 yarn 和后端资源调度的 YARN 不是一回事

这个问题看似离谱，但在搜索引擎里出现的频率高到惊人。有大量“spark on yarn cpu只能用1个是为什么”这类检索词，看起来是后端大数据相关的问题，但提问者输入的关键词里包含 yarn，前端项目里搜 yarn 命令时自然也会被带出来。

前端的 yarn 是一个 JavaScript 包管理工具；大数据领域的 YARN 是 Hadoop 体系里的资源调度器。两者名字相同，但技术栈、使用场景、文件格式毫无关系。你给 spark 作业调 YARN 的 executor 数量，和前端项目里执行yarn add vue，没有任何交集。如果团队里既有做数据平台的同事、又有做前端的同事，共享聊天群或者协作文档里，搜 yarn 关键词时注意加一下上下文前缀，比如“前端 yarn 命令”和“spark YARN 配置”，否则很容易搜出大量完全无关的内容。这个澄清不是水字数，而是我在企业里实际看到的检索困境——不少公司知识库里，前端 yarn 命令和数据平台 YARN 文档被混在同一个标签里，初学者一搜就懵。

2. 命令地图：从初始化到日常维护，一张表对照着抄

2.1 项目初始化与依赖安装命令对照

命令地图的核心价值，是让你在做同一件事时，三个工具都能找到对应的指令。先看最基础的初始化与安装：

这里要特别注意--save参数。npm 在旧版本中必须显式加--save，依赖才会写入 package.json，但 npm v5 之后--save已经是默认行为，写不写没区别。yarn 和 pnpm 从设计之初就把“保存到 package.json”作为默认动作，不需要额外加--save。很多老教程里还在强调npm install xxx --save，你直接抄的话不会报错，但属于无效操作。

还有一个默认行为差异值得展开：npm v7 开始会自动安装 peerDependencies。在 npm v6 时代，peerDependencies 只是“提示”，装不装由包自己处理；npm v7 改成“默认帮你装上”，这导致很多老项目升级 npm 版本后突然多了一堆依赖，甚至引发 ERESOLVE 冲突。yarn 1.x 和 pnpm 对 peerDependencies 的处理策略也各不相同，这也是为什么同一个项目换一个包管理器就会报出一堆 peer 依赖版本冲突。我的建议是：项目选定一个包管理器后，尽量不要频繁切换，转到 pnpm 或 yarn 这类更严格的工具时，要预留时间处理 peer 依赖版本调整。

2.2 依赖的增删改查和版本管理

除安装外，日常更新依赖也有一组对应命令：

npm ci和npm install的区别值得单独说一句。npm ci会严格按照 lock 文件安装，并且先删除整个 node_modules，做到完全可复现，所以 CI 流水线上应该用npm ci，本地开发用npm install即可。yarn 1.x 里没有镜像的yarn ci命令，但yarn install --frozen-lockfile可以做到相同效果：lock 文件有变动时直接报错，不会静默更新。pnpm 里对应的是pnpm install --frozen-lockfile。

yarn why和pnpm why是排查依赖来源的神器。比如你的代码里明明只引用了 A，A 内部又依赖了 B，你想知道 B 是被谁带上来的，执行yarn why B或pnpm why B就能看到完整的引用路径。npm 生态里对应的是npm ls B，但 npm ls 输出经常非常冗长，视觉上不如 why 命令清爽。这个命令在排查重复依赖和版本冲突时极其重要，建议养成习惯。

2.3 运行脚本与临时执行工具：run、exec、dlx 的区别

pnpm 和 yarn 都支持脚本执行，而且规则比 npm 更严格。npm 运行脚本时，会把node_modules/.bin临时放进 PATH，所以你在npm run build内部调webpack、vite等命令都能识别。yarn 和 pnpm 同样如此。但如果你在终端里直接执行vite命令，三个工具都会提示“找不到”，除非全局安装过。

关于临时执行包，这个点特别容易踩坑。npm 生态的npx很强大，它会在临时目录安装包并执行，用完自动清理，不会污染你的全局环境。yarn 1.x 没有直接对应的场景，很多人用yarn global add来顶替，这其实是把临时工具变成全局工具，容易造成环境里一堆乱七八糟的全局包。yarn Berry 引入了yarn dlx，语义才和 npx 对齐。pnpm 对应的是pnpm dlx。所以如果你买了教程用了yarn dlx但安装的是 yarn 1.x，铁定报“找不到命令”。遇到这种情况，要么升级 yarn 到 Berry，要么老老实实用npx。

2.4 缓存、离线安装与磁盘清理

缓存和离线安装是一对关联操作。npm 的缓存在用户主目录下的_cacache里，yarn 1.x 在~/.cache/yarn，pnpm 的 store 则位于~/.local/share/pnpm/store或者你手动指定的位置。pnpm 的缓存概念跟前两者不太一样，它的 store 不是“缓存”而是“内容寻址存储库”，所有项目共享，所以理论上 pnpm 几乎天然支持离线安装——只要 store 里有对应的包，断网也能装。

离线安装这在公司内网、服务器断网环境特别实用。你可以在有网的机器上先执行pnpm install把 store 填满，然后把整个 store 目录拷贝到离线机器，再执行pnpm install --offline，就能完全脱离外网完成安装。Linux 服务器上离线安装 pnpm 也是同样原理：先在有网的机器上用 npm 全局装好 pnpm，拿到 bin 路径，再把 node_modules 目录和可执行文件一并拷到目标机器，配置好 PATH 即可。这里有个小细节：pnpm store prune 只清除未被任何项目引用的孤立包，不会清掉正在使用的文件，所以定期执行是安全的。

3. 实战：在一台机器上让三款包管理器和平共处

3.1 用 nvm 管理 Node 版本，从源头规避环境变量混乱

很多环境问题的根子出在 Node 版本管理上：有人从官网下载最新版 Node，然后用它全局安装了三个包管理器；后面某个工具要求切换 Node 版本，又把 PATH 改来改去，最终什么命令都找不到。我个人的建议是，把这套东西全部交给 nvm 管理。

macOS/Linux 下的安装方式是：

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash

Windows 没有原生 nvm，而是用 nvm-windows：

# 到 GitHub 下载 nvm-setup.exe 安装包，然后执行： nvm install 20 nvm use 20

用 nvm 之后，Node 和 npm 版本跟随当前使用的 Node 版本切换，全局安装的包也会跟随分区隔离，避免多个主版本混在同一套 PATH 里互相覆盖。这里要强调的是，nvm 只负责 Node/npm 的版本切换，它本身不会自动管理 yarn 和 pnpm。yarn 和 pnpm 的安装方式，我推荐优先考虑 Corepack。

Corepack 是 Node.js 官方从 16.13 开始内嵌的实验性工具，专门用于管理 yarn 和 pnpm。你不需要再手动全局安装，只需要在项目里启用：

corepack enable corepack prepare pnpm@10 --activate

执行后，pnpm 命令就会自动可用，而且它由 Corepack 统一管理版本，完全绕开“全局安装到哪个目录”、“PATH 里有没有这个目录”这些琐碎问题。如果你的 Node 版本较老，Corepack 默认没有启用，可以先开启：

corepack enable

然后再激活目标版本。这比我下面要讲的“npm install -g 手动装”要干净得多，也更容易维护。不过 Corepack 在 Node 20 的某些小版本中经历过一次调整，如果遇到corepack: command not found，多半是 Node 安装方式不带 Corepack 组件，这时再用 npm 手动全局安装也不迟。

3.2 npm 环境变量 Path 配置：报“不是内部或外部命令”时的标准排查流程

“npm 不是内部或外部命令”和“pnpm' 不是内部或外部命令”这类错误，搜索引擎里常年霸榜。核心原因只有一个：系统 PATH 里没有包含对应可执行文件的目录。排查和解决其实有固定套路，我总结为四步。

第一步，确认安装位置。如果是从 nodejs.org 官网下载的安装包，安装目录通常在C:\Program Files\nodejs或者你自定义的路径；如果用 nvm 管理，则位于 nvm 安装目录下的某个版本文件夹里。可以通过命令确认：

# Windows where npm # macOS / Linux which npm

如果能输出路径但运行时报错，说明 PATH 有问题；如果 where/which 都查不到，说明 npm 可执行文件本身没被识别。

第二步，打开系统环境变量编辑器，检查 PATH 里是否包含 npm 所在目录。Windows 路径要特别注意，C:\Program Files\nodejs带空格，旧版安装包偶尔会把路径写错，或者被安全软件清掉某个关键项。

第三步，如果 PATH 里确实没有，点击“新建”把 nodejs 目录加进去，同时把全局模块目录也加进去。查看全局模块目录的命令是：

npm config get prefix

在 Windows 上通常是C:\Users\你的用户名\AppData\Roaming\npm，macOS 上通常是/usr/local或者/usr/local/bin。这个全局目录也要加入 PATH，否则会出现“npm 能跑，但 npm install -g 出来的工具命令找不到”。

第四步，改完 PATH 之后，一定要新开一个终端窗口让环境变量重新加载，然后执行：

node -v npm -v

两个命令都能输出版本号，才算配置成功。

你可能会遇到另一个变种：npm : 无法加载文件 C:\Program Files\nodejs\npm.ps1，因为在此系统上禁止运行脚本。这个不是 PATH 问题，而是 PowerShell 的脚本执行策略限制。npm 会在 Windows 上生成 npm.ps1，PowerShell 默认禁止运行此类脚本，所以直接报错。解决方案有两条路：一是以管理员身份打开 PowerShell，执行：

Set-ExecutionPolicy RemoteSigned

这条命令允许本地创建的脚本运行，远程下载的脚本必须经过签名才能运行，兼顾安全与便利，是当前最推荐的方式。二是如果不想动 PowerShell 策略，可以改用 CMD 来运行 npm 命令，但这样就绕过了 PowerShell 的便利性，并非长久之计。注意，不要随便跑到Set-ExecutionPolicy Unrestricted，那等于把安全策略全关掉，不是正常运维该有的行为。

3.3 用 npm 全局安装 yarn 和 pnpm，并配置国内镜像源

如果不用 Corepack，最常见的方式还是用 npm 全局安装：

npm install -g yarn npm install -g pnpm

这里会出现一个有意思的问题：用 npm 去安装 pnpm，那么 pnpm 的全局包目录实际上就是 npm 的全局目录。你需要确保npm config get prefix这个目录在 PATH 中，否则执行pnpm -v也会报“不是内部或外部命令”。

安装完成后，三款工具默认的 registry 都是 npm 官方源。在国内环境下，从官方源拉包速度感人，而且经常超时。建议统一切换到国内镜像源。现在主流方案是 npmmirror，也就是原来淘宝镜像的新域名：

# npm npm config set registry https://registry.npmmirror.com # yarn 1.x yarn config set registry https://registry.npmmirror.com # pnpm pnpm config set registry https://registry.npmmirror.com

这里有一个非常容易踩的雷：老教程里写的淘宝镜像域名是https://registry.npm.taobao.org。这个域名在 2022 年已经停止服务，如果你现在还在用它，会看到类似npm ERR! code CERT_HAS_EXPIRED或certificate has expired的报错。原因不是你的网络问题，也不是 npm 坏了，而是旧域名的证书已经过期、服务早已下线。解决办法就是换成https://registry.npmmirror.com。

切换镜像后,还要注意 lock 文件里的 resolved 字段。如果项目之前用的是官方源生成的 lock 文件，里面的下载地址都指向 registry.npmjs.org，切换到国内源后，重新安装时是否要重新拉取 lock 呢？实际上 package-lock.json 和 pnpm-lock.yaml 都会记录每个包的完整下载地址，如果里面写的是官方源，安装时同样会从官方源下载，不会因为配置了镜像就自动改写。所以切换到国内源之后，建议删掉 lock 文件重新生成一次，或者用pnpm install --force让 lock 文件里的 resolved 字段刷新。这个细节很折磨人，但知道了就不会再犯。

3.4 pnpm 10 的 approve-builds：安装后必须处理的信任审批

pnpm v10 带来的一个让很多人困惑的新机制，就是依赖构建脚本的审批。它的背景是：npm 生态曾有大量恶意包通过 postinstall 脚本在安装阶段执行挖矿、盗取环境变量等恶意操作。为了降低攻击面，pnpm v10 默认不再执行依赖包自身的 build 脚本，只对 package.json 中显式声明了onlyBuiltDependencies的包放行。

所以你执行pnpm install之后，如果输出中有一行：

Ignored build scripts: esbuild. Run "pnpm approve-builds" to pick which dependencies should be allowed to run.

千万不要以为安装失败。你需要运行：

pnpm approve-builds

这里用 esbuild 举例特别合适，因为 esbuild 必须要执行 postinstall 才能拉取到平台相关的二进制文件，否则运行时直接报错。执行pnpm approve-builds后会进入一个交互界面，列出所有声明了 build 脚本的依赖，你用方向键切换、空格选中再回车确认即可。但交互式界面在 CI 或者脚本里没法操作，所以更推荐直接在 package.json 中声明白名单：

{ "pnpm": { "onlyBuiltDependencies": ["esbuild", "sharp", "node-sass"] } }

如果是 monorepo 项目，这个配置要在 pnpm-workspace.yaml 旁边的根 package.json 里写，不能写在某个子包中。

3.5 项目级 .npmrc、用户级 .npmrc 和 pnpm-workspace.yaml 的优先级关系

配置镜像源和审批白名单时，很多人会混淆 npmrc 文件的归属。实际上 npm、yarn、pnpm 都支持通过配置文件设置 registry 等参数，它们的查找顺序大同小异。以 npm 为例，配置文件优先级从高到低依次是：

项目根目录的 .npmrc 优先级最高，这也是 monorepo 里经常用到的技巧：比如某个子项目必须走官方源，而其他项目走镜像，就在那个子项目里单独放一个 .npmrc 覆盖 registry。pnpm 还额外支持 pnpm-workspace.yaml，用于 monorepo 的 workspace 配置。pnpm 安装时对依赖的提升策略会参考该文件中的 packages 字段。

我见过一个真实案例：团队成员各自在用户目录下配置了不同的 registry，结果有的人安装的是官方源包、有的人安装的是镜像源包，lock 文件不断被改动。后来定下规矩，所有 registry 配置一律写进项目根目录的 .npmrc，用户目录下不存任何 registry 配置，才彻底终结了这场混乱。如果你的团队也遇到“为什么 package-lock.json 总是有 diff”之类的问题，先检查一下每个人用户目录下的 .npmrc 是否一致。

4. 高频报错排查实录：每一个都是搜索引擎里出现过的词条

4.1 “'pnpm' 不是内部或外部命令”：“无法将 pnpm 项识别为 cmdlet”怎么办

这类报错的本质，就是上文说过的 PATH 问题。但有一个很容易忽略的情景：你通过 npm 全局安装了 pnpm，但 npm 的全局目录不在 PATH 里；另一种情况更隐蔽，你用 Corepack 激活了 pnpm，但当前项目的 package.json 里没有启用 packageManager 字段，Corepack 不会自动接管命令。

我自己排查的固定流程是，先分清“命令完全找不到”和“PowerShell 禁止执行”两类错误，然后用三步法确认：

# 第一步：看 pnpm 装在哪 where pnpm # Windows which pnpm # macOS/Linux # 第二步：查看 npm 全局目录 npm config get prefix # 第三步：确认目录是否在 PATH 里 echo $env:PATH # PowerShell echo $PATH # bash/zsh

如果 pnpm 安装在 npm 的全局目录下，而这个目录不在 PATH 里，把目录加进 PATH 即可解决。如果 where/which 都查不到，说明根本没装上，重新执行安装。

有一个细节我认为很值得提：用npm install -g pnpm安装的 pnpm 是一个 shell 脚本（Windows 上还有 pnpm.cmd 和 pnpm.ps1），它依赖 Node 环境运行。如果你后面切换了 Node 版本，全局 pnpm 可能因为路径变化而失效。这就是为什么我推荐 Corepack 多一点——它绑定的是当前 Node 版本，切换 Node 时自动同步对应版本，少了很多糟心事。

4.2 cert_has_expired：旧淘宝镜像证书过期与镜像源切换

搜索引擎里排得很靠前的npm ERR! code CERT_HAS_EXPIRED和request to https://registry.npm.taobao.org/xxx failed, reason: certificate has expired，十有八九是历史遗留的淘宝镜像引用。除了手动改 .npmrc，也有一种可能是 lock 文件里记录了旧域名。既然在旧域名已经无法访问，你需要把镜像源统一换到新域名https://registry.npmmirror.com，然后重新生成 lock 文件。

如果公司内网使用自建私有源，SSL 证书是内网签发的自签证书，npm 会因证书不受信任报错。这时很多人会直接关掉严格校验：

npm config set strict-ssl false

我不推荐长期这么干。更稳妥的做法是把自签证书加到系统信任链里，或者配置 CAs 字段指向公司的根证书文件。关闭 strict-ssl 相当于把 HTTPS 降级为裸奔，依赖包内容可以被任意中间人篡改，这在生产环境里风险太大。

4.3 unsupported url type “catalog:”: 旧版本工具不支持新协议

npm error unsupported url type "catalog:"这个报错，是 pnpm 的 catalog 特性与传统 npm 命令之间的一次“版本代沟”。catalog 是 pnpm v9.5+ 引入的一个 monorepo 依赖目录规则，允许你在 pnpm-workspace.yaml 或 package.json 里定义一个“目录中心”，统一管理多个包的版本号。当其他工具（比如旧版本 npm 或旧版本 pnpm）尝试解析这种 catalog 协议时，会直接抛出Unsupported URL Type "catalog:"。

解决办法分两步。第一，看发命令的工具版本：比如 pnpm 版本太旧，不识别 catalog 协议，就先升级：

npm install -g pnpm@latest pnpm --version

第二，如果工具版本已经比较新但依然报错，检查项目中是否引用了 catalog 配置但没有正确声明：

{ "dependencies": { "lodash": "catalog:" } }

catalog 协议需要 pnpm-workspace.yaml 里定义对应的版本目录，比如：

packages: - 'packages/*' catalog: lodash: ^4.17.21

如果 catalog 定义缺失，工具也会报错。这个报错在 monorepo 场景比较多见，单包项目一般用不上。我的建议是，如果项目没有多包依赖统一管理的强需求，不要为了“用新功能”而引入 catalog，旧项目里混用反而增加排障成本。

4.4 cannot read properties of null (reading ‘edgesOut’): lock 文件损坏与重建

npm ERR! Cannot read properties of null (reading 'edgesOut')这个错误非常眼熟。官方 issue 里给出的核心结论是：package-lock.json 已经损坏或与 package.json 不一致。常见诱因包括：多个包管理器轮流修改了同一个 lock 文件、手工编辑 package-lock.json 时操作失误、安装过程中被强制中断导致 lock 文件写入了一半。

处理方式其实很粗暴：

rm -rf node_modules package-lock.json npm cache clean --force npm install

三步走之后，绝大多数 edgesOut 报错都能消失。如果项目里同时存在 package-lock.json 和 pnpm-lock.yaml，或者 yarn.lock 被混着改过，建议确认一下团队约定的唯一包管理器，然后删掉其余文件的 lock。混用包管理器造成 lock 文件互相覆盖的案例，我在多个团队里都见过，排查到最后通常都是“谁先 commit 谁赢”的闹剧。提前约定清楚，比事后修文件重要得多。

4.5 deprecated、unknown user config 等警告：哪些该管，哪些可以无视

日常安装经常看到类似npm warn deprecated node-domexception@1.0.0: use your platform's native dome的输出。deprecated 只是“该包已标记弃用”，不代表安装失败。要不要管，取决于你项目中是否真的依赖它。如果只是一个间接依赖、并且它的功能被其他替代包覆盖，忽略即可。如果它是你的核心依赖（比如某个重要构建工具），就要评估是否升级到替代版本。

npm warn unknown user config "home"这类警告则表示 .npmrc 文件里存在一个 npm 不认识的配置项。出现原因多数是用户把别的工具的配置写进了同一个 .npmrc，或者手工复制配置时带了多余参数。可以通过npm config list查看当前生效配置，定位是哪一行出了问题。它也只是个警告，不影响安装结果，但建议清理干净，否则疑难问题排查时会把注意力带偏。

还有一个零散但频繁的词条：npm ERR! code EUNSUPPORTEDPROTOCOL。这个通常出现在 lock 文件或手动指定的依赖地址里带有非 http/https 协议，比如 git+ssh、file:、catalog: 等，而当前 npm 版本不支持或没有正确识别。如果你用的是 GitHub、GitLab 作为依赖源，默认会存成git+https://github.com/xxx/yyy.git，理论上 npm 支持，但某些私有化环境可能需要配置 SSH 协议。这类问题的核心是检查 package.json 中对应依赖的版本字符串，确认协议写法无误。

5. 发布 npm 包与搭建 Nexus 私有仓库：从本地验证到全团队可用

5.1 发布 npm 包：登录、版本号、文件白名单和本地验证

发布 npm 包是挺多前端团队的刚需——公共组件、工具库、配置包都需要做成包给多个项目复用。这个流程基本是固定的。

第一步，本地登录。

npm login npm adduser

输入账号、密码和邮箱即可。如果团队用私有仓库，需要先切换 registry 到私有源再登录。

第二步，确认版本号。npm 发布遵循 semver 语义化版本，npm version patch会直接把 package.json 里的版本号从 1.0.0 改成 1.0.1 并自动打 tag，minor和major同理。发布前一定确认版本号不是已经发布过的，否则 npm 会拒绝同名同版本发布。

第三步，控制发布内容。npm 默认会把整个目录都发上去，除了 .gitignore、.npmignore 里的排除项。为了精简包体、避免把测试文件和源码泄露上去，我建议用 files 字段显式声明白名单：

{ "files": ["dist", "types", "README.md"] }

配置 files 字段之后，发布时只会包含列出的文件和文件夹，比 .npmignore 黑名单模式更可控。

第四步，发布前本地验证。写了一个包直接 publish，回去发现 dist 没打出来，这是新手常见的翻车现场。这里我强烈推荐两个命令：npm pack和npm link。

npm pack

这个命令会在本地生成一个 tgz 文件，里面正好就是发布后的包内容。解压看一下，dist、types、package.json、README 都在，不必要文件没混进来，才放心发布到 registry。

npm link则用于本地项目联调：在包目录执行npm link，再到引用方项目执行npm link 包名，本地开发时可以让引用方直接使用最新代码，避免了反复发布消耗版本号的痛苦。

第五步，正式发布。

npm publish

如果这是私有包，需要在 package.json 里配置：

{ "publishConfig": { "registry": "https://your-nexus-host/repository/npm-private/" } }

否则默认发到官方公共源。

5.2 用 Nexus 搭建 npm 私有仓库：group 仓库与 .npmrc 配置

Nexus 是应用广泛的私服方案，支持 maven、pypi、npm 等多种格式。用 Nexus 做 npm 私有仓库时，通常需要创建三个类型的仓库：

• npm(proxy)：代理远程源，比如代理 npmmirror 或官方源。
• npm(hosted)：存放团队私有包。
• npm(group)：把代理仓库和私有仓库聚合在一个 URL 下，客户端统一访问 group 即可。

创建好之后，每个仓库都有一个访问 URL，形如https://your-nexus-host/repository/npm-group/。把这个 URL 配置到项目根目录的 .npmrc 里：

registry=https://your-nexus-host/repository/npm-group/

这样开发机既能发布私有包，又能拉取公共依赖。

这里需要提醒的是 Nexus npm 私有仓库的认证。发布私有包时，nexus 会要求认证，npm 的 token 配置方式不是简单的“账号密码自动记住”，而是生成一个 token 写入 .npmrc：

npm login --registry=https://your-nexus-host/repository/npm-group/

之后 npm 会在用户主目录 .npmrc 里写入一个 NpmToken。如果团队使用 CI/CD，更要确保 token 以安全变量的方式注入环境，而不是明文写进代码仓库。这算不上安全高级知识，但确实经常被忽略。

5.3 lock 文件与审计：安全性地看待依赖引入

无论你选哪个包管理器，依赖安全性都不能完全依赖开发机上的安装结果。npm 提供了 audit 命令：

npm audit

pnpm 对应的是：

pnpm audit

yarn 1.x 也有yarn audit。audit 会基于当前依赖树，到 registry 上比对已知漏洞库，给出风险等级和建议修复版本。但这条命令依赖 registry 是否支持审计接口，私有源如果不接入审计数据，返回的往往是“无法获取”。内网开发环境遇到这种情况，别迷信 audit 的输出，可以定期在能联网的机器上跑一次审计，再把结果带回内网处理。

还有一点要强调：lock 文件本身是一份“依赖清单快照”，把锁文件纳入版本控制，有利于保证团队所有人安装到完全相同的依赖树。很多初学者把 lock 文件加进 .gitignore，这个习惯非常不好。node_modules 不进版本库，但 lock 文件必须进。它是项目可复现性的最后一道防线，也是排查依赖问题时的第一线索。

6. 新项目和老项目该怎么选：经验建议与迁移注意

做了这么多年，我得出一个很朴素但可靠的选择原则：新项目优先用 pnpm，老项目尊重现状，不轻易换工具。为什么这么排？

新项目没有历史包袱，可以从一开始就享受 pnpm 的磁盘效率、安装速度和严格的依赖隔离。pnpm 的符号链接结构对新的构建工具链（Vite、Webpack 5+、Rollup）兼容性已经相当好，很少出现无法识别的问题。更关键的是，pnpm 严格的依赖声明机制会倒逼团队养成好习惯：哪个包被直接使用，就必须出现在 package.json 里，这大大减少了“依赖隐式存在”造成的环境依赖坑。

老项目如果已经用 npm 跑通，线上没有事故，完全没必要为了“更先进”而换。换包管理器最痛苦的点不是安装命令不同，而是 lock 文件、node_modules 布局、peer 依赖规则全部要重新对齐。我亲历过把一个中型项目从 npm 迁到 pnpm，表面看着很简单：删除 package-lock.json、删除 node_modules、执行 pnpm install，结果构建时爆出大量 peer 依赖冲突和原生模块路径问题，拖了整整三天才调到能正常出包。所以老项目迁移的前提是：有专门的时间窗口、有完整的自动化测试保障回归、有负责人兜底，而不是在业务冲刺期临时起意。

如果一定要迁移，我建议按这个顺序推进。第一步，评估项目依赖中是否有需要通过 postinstall 编译的原生模块（electron、node-sass、sharp、esbuild 等），这些是 pnpm 符号链接模式下最需要小心的群体。第二步，在迁移分支上执行 pnpm install，关注 pnpm approve-builds 的输出，逐个确认需要放行的依赖。第三步，跑一遍完整的 build、test、lint 流水线。第四步，合并分支后观察线上稳定运行一段时间，让问题在可控范围内暴露。这四步缺了哪一环，都容易在发布窗口期翻车。

最后再分享一个实际踩过坑之后的体会：同一个项目，尽量不要混用包管理器。npm、yarn、pnpm 的 lock 文件格式各不相同，混用会导致 lock 文件不断冲突，最终不得不删干净重新安装。这一点说出来似乎人人明白，但在多人协作中，每个人都有自己偏好的工具，如果约定不明确，混用只是时间问题。我的做法是在项目 README 的开发指南里写明“本项目统一使用 pnpm，禁止使用 npm/yarn 单独安装依赖”，同时在 CI 里加一步包管理器检测，比如执行packageManager字段核验，不符合就 fail。

工具本身没有好坏，关键在于理解了机制再去用。命令可以随时查，机制一旦理解，换几次工具都不会慌。这份命令地图和排查笔记，算是这些年折腾三款包管理器的一份沉淀，希望对你有些许帮助。