前端 Node 全家桶

前言：为什么需要这一套 nvm + npm + pnpm + Yarn + nrm？

刚入门前端时，常见困惑是：

项目 A 要 Node 16，项目 B 要 Node 20，本机只能装一个？
npm install 慢、占磁盘、node_modules 巨大？
npm、pnpm、Yarn 到底用哪个？锁文件能不能混？
公司内网 npm 源、淘宝镜像、官方源来回切？配置文件一直找？

这套工具各管一层，组合起来就是完整工作流：

工具	管什么	一句话
nvm	Node 版本	多项目多版本 Node 随意切换
npm	包管理（Node 自带）	零配置、教程最多、发包标准工具
pnpm	高效包管理	省磁盘、装得快、monorepo 体验好
Yarn	包管理（Facebook 系）	经典仓库多；Yarn 4（Berry）现代特性全
nrm	镜像源	一条命令切换 registry（三者通用）

┌──────────┐    安装/切换     ┌─────────────────────┐    registry    ┌──────────┐
│   nvm    │ ──────────────▶ │ npm / pnpm / Yarn   │ ◀───────────── │   nrm    │
│ Node版本  │                 │      装包跑脚本       │                │  镜像源   │
└──────────┘                 └─────────────────────┘                └──────────┘

注：这里只做简单的介绍，缓存配置这些需要可以另行查找资料。

一、nvm：Node 版本管理

1.1 是什么？

nvm（Node Version Manager）让你在同一台机器上安装多个 Node 版本，按项目切换，互不影响。

Windows 用户注意： 官方 nvm 不支持 Windows，请用 nvm-windows。命令大体相同，路径与安装方式略有差异。
找到仓库下方的 latest installer，然后找到 assets 的 exe 进行下载安装即可。

1.2 安装（macOS / Linux）

# 官方安装脚本（版本号以官网为准）
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash

# 重新加载 shell
source ~/.bashrc   # 或 ~/.zshrc
nvm --version

Windows（nvm-windows）： 下载安装包，安装后重开终端，执行 nvm -v 验证。若 PowerShell 报脚本策略，见 10.2.1。

1.3 常用命令

# 查看可安装版本
nvm ls-remote          # macOS/Linux
nvm list available     # Windows

# 安装并使用
nvm install 26.5.1
nvm install 22.23.2
nvm use 22.23.2

# 查看已安装
nvm ls

# 设置默认版本（新开终端生效）
nvm alias default 22.23.2

# 查看当前版本（npm 随 Node 自带，pnpm/Yarn 靠 Corepack）
node -v
npm -v

1.4 项目级版本锁定：`.nvmrc`

项目根目录新建 .nvmrc：

22.23.2

进入目录后：

nvm use          # 自动读 .nvmrc
# 若未安装会先提示 nvm install

团队规范： 每个仓库提交 .nvmrc，CI 里读同一版本，避免「我本地能跑你那边不行」。

1.5 常见问题

问题	处理
`nvm use` 后版本没变	检查是否多个 Node 安装源冲突（如曾用安装包装过 Node）
全局包装「消失」	nvm 下每个 Node 版本有独立全局包，切换版本需重装或改用 Corepack
Windows 权限 / 脚本失败	管理员装 nvm-windows；PowerShell 执行策略见 10.2

二、包管理器总览：npm / pnpm / Yarn 怎么选？

Node 生态里有三大包管理器。它们共用同一套 registry（npmjs），但锁文件、目录结构和命令不同，不能混用。

2.1 三者一句话

工具	来源	现状
npm	Node 内置	默认选项，文档/教程最多，`npm publish` 发包事实标准
pnpm	独立项目	新仓库、Monorepo 首选之一，磁盘与速度优势明显
Yarn	Meta 开源	Yarn 1（Classic）老项目常见；Yarn 4（Berry 系）为当前主线，通过 Corepack 启用

Yarn 版本别搞混： Yarn 1 与 Yarn 2+ 差异很大。Yarn 1 接近 npm；Yarn 4 默认可走 PnP（无传统 node_modules），也可配置 nodeLinker: node-modules 兼容老工具链。

2.2 核心指标对照表

对比项	npm	pnpm	Yarn（Berry 4）
安装方式	随 Node 自带	Corepack / 独立脚本	Corepack（推荐）
锁文件	`package-lock.json`	`pnpm-lock.yaml`	`yarn.lock`
Monorepo 配置	`package.json` → `workspaces`	`pnpm-workspace.yaml`	`package.json` → `workspaces`
node_modules	扁平/嵌套，易重复	内容寻址 + 硬链接，全局 store	默认 PnP；可切 `node-modules`
磁盘占用	较高	最低	PnP 低；node-modules 模式与 npm 类似
安装速度	中等	通常最快	快（Berry 优化明显）
幽灵依赖	易出现	默认严格	PnP 最严；node-modules 模式类似 npm
临时跑 CLI	`npx`	`pnpm dlx` / `pnpm exec`	`yarn dlx`
CI 严格安装	`npm ci`	`pnpm install --frozen-lockfile`	`yarn install --immutable`
版本锁定字段	—	`"packageManager": "pnpm@x"`	`"packageManager": "yarn@x"`
国内镜像	`.npmrc` / nrm	读 `.npmrc`	读 `.npmrc` + `.yarnrc.yml`

幽灵依赖： A 依赖 B，B 依赖 C，你直接 import C 但 package.json 没声明 C——换包管理器或升级后可能报错。pnpm / Yarn PnP 对此更严格。

2.3 命令对照表（日常开发）

操作	npm	pnpm	Yarn（Berry）
初始化	`npm init -y`	`pnpm init`	`yarn init -y`
安装全部依赖	`npm install`	`pnpm install` / `pnpm i`	`yarn install` / `yarn`
加生产依赖	`npm install axios`	`pnpm add axios`	`yarn add axios`
加开发依赖	`npm install -D vite`	`pnpm add -D vite`	`yarn add -D vite`
移除依赖	`npm uninstall axios`	`pnpm remove axios`	`yarn remove axios`
跑脚本	`npm run dev`	`pnpm dev`	`yarn dev`
CI 严格装	`npm ci`	`pnpm i --frozen-lockfile`	`yarn install --immutable`
临时执行 CLI	`npx create-vue`	`pnpm dlx create-vue`	`yarn dlx create-vue`
升级依赖	`npm update`	`pnpm update`	`yarn up`
Monorepo 跑子包	`npm run dev -w app`	`pnpm --filter app dev`	`yarn workspace app dev`
递归所有包	`npm run build -ws`	`pnpm -r build`	`yarn workspaces foreach run build`

2.4 按场景选型：该用哪个？（参考表）

场景	推荐	理由
入门 demo、跟着官方文档敲	npm	零额外安装，资料最多
新建业务仓库	pnpm	磁盘/速度/monorepo 综合最优
已有 Yarn 1 老项目	继续 Yarn 1 或计划迁移	别混用 lock；迁移需团队评审
已有 Yarn 4 / Berry 仓库	继续 Yarn	如 Next.js、部分 React 生态仓库
Monorepo 从零搭建	pnpm 或 Yarn 4	两者 workspace 都成熟；pnpm 上手更简单
工具链只认扁平 `node_modules`	npm 或 pnpm + `shamefully-hoist`	或 Yarn 4 设 `nodeLinker: node-modules`
想极致杜绝幽灵依赖	pnpm 或 Yarn PnP	PnP 最严，但部分工具需适配
发 npm 公开包	npm publish	开发阶段仍可用 pnpm/Yarn
团队已统一某种 lock	跟仓库走	看 `package-lock.json` / `pnpm-lock.yaml` / `yarn.lock`
Docker 多阶段构建	pnpm 或 Yarn Berry	均支持 fetch/cache 优化；按仓库 lock 选

建议：

没有历史包袱 → pnpm
克隆下来的项目用什么 lock → 就用什么，不要换
教程/小脚本 → npm 足够

2.5 混用禁忌

不要这样做	后果
同一仓库 npm install 后又 pnpm install	两套 lock，MR 互相覆盖，CI 随机失败
删 lock 不提交就 push	同事/CI 装到不同版本
全局混装多个包管理器版本	与 Corepack 冲突，版本对不上
nrm 切了源但项目 `.npmrc` 写死别的	以为换了源其实没换

团队只保留一种锁文件，并在 README 写清：

本项目使用 pnpm，请勿使用 npm/yarn install。
安装：corepack enable && pnpm install

三、npm：Node 自带的包管理器

3.1 核心文件

my-app/
├── package.json
├── package-lock.json
└── node_modules/

3.2 常用命令

npm init -y
npm install
npm install axios
npm install -D eslint
npm run dev
npm ci                         # CI：严格按 lock 安装
npm audit
npm publish

3.3 npm vs npx

npm：装包、管项目
npx：临时执行 CLI，不必全局安装

npx create-vue@latest my-vue-app

四、pnpm：更快、更省磁盘

4.1 安装

corepack enable pnpm
pnpm -v

# 或独立脚本：https://pnpm.io/installation

4.2 Monorepo 示例

pnpm-workspace.yaml：

packages:
  - 'packages/*'
  - 'apps/*'

子包引用：

{
  "dependencies": {
    "ui": "workspace:*"
  }
}

pnpm install
pnpm --filter web dev
pnpm -r build

4.3 `.npmrc` 常用配置

registry=https://registry.npmmirror.com
engine-strict=true
# shamefully-hoist=true          # 老项目兼容时可开
public-hoist-pattern[]=*types*
public-hoist-pattern[]=*eslint*

4.4 从 npm / Yarn 迁移到 pnpm

rm -rf node_modules package-lock.json yarn.lock
corepack enable pnpm
pnpm install
git add pnpm-lock.yaml pnpm-workspace.yaml .npmrc

五、Yarn：Classic 与 Berry（Yarn 4）

5.1 版本区分

版本	俗称	状态	特征
Yarn 1.x	Classic	维护模式	命令 `yarn add`，与 npm 类似，老项目多
Yarn 2+	Berry	当前主线	Yarn 4 为代表；PnP、Plug'n'Play、Zero-Install 等
启用方式	—	Corepack	`corepack enable` + `packageManager` 字段

5.2 安装 Yarn 4（Berry）

corepack enable
corepack prepare yarn@stable --activate
yarn -v

# 或在项目中锁定
corepack use yarn@4.9.1

package.json：

{
  "packageManager": "yarn@4.9.1"
}

5.3 常用命令（Berry）

yarn install              # 安装依赖
yarn add vue              # 加依赖
yarn add -D vite          # 加 dev 依赖
yarn remove axios
yarn dev                  # 跑 scripts（可省略 run）
yarn dlx create-vue       # 类似 npx
yarn install --immutable  # CI 严格模式（等同 --frozen-lockfile）
yarn up                   # 升级依赖

5.4 Monorepo（Yarn workspaces）

根目录 package.json：

{
  "private": true,
  "workspaces": ["packages/*", "apps/*"]
}

yarn install
yarn workspace web dev
yarn workspaces foreach run build

5.5 `.yarnrc.yml` 常见配置

# 国内镜像（Berry 也读 .npmrc 的 registry，二者配一个即可）
npmRegistryServer: "https://registry.npmmirror.com"

# 兼容只认 node_modules 的工具（Webpack 老插件、部分 IDE）
nodeLinker: node-modules

# 默认是 plug'n'play（无 node_modules），新项目可按需开启
# nodeLinker: pnp

5.6 Yarn 1 → Yarn 4 迁移提示

不要直接在 Yarn 1 仓库里 corepack use yarn@4 就完事，需按官方迁移指南逐步来
Berry 会生成 .yarn/ 目录和 .yarnrc.yml，一并提交
团队 CI 改为 yarn install --immutable

六、Corepack：统一管理 npm / pnpm / Yarn 版本

Node 16.13+ 自带 Corepack，避免 npm i -g pnpm/yarn 造成版本混乱：

npm install -g corepack@latest
corepack enable

# 按项目 package.json 的 packageManager 自动切换版本
corepack enable pnpm
corepack enable yarn

# 手动锁定
corepack use pnpm@10.12.0
corepack use yarn@4.9.1

建议： 团队统一 Corepack + packageManager 字段，clone 下来版本自动对齐。

七、nrm：镜像源一键切换

7.1 是什么？

nrm 管理 registry 地址。npm、pnpm、Yarn 都读 registry 配置，nrm 改的是用户级 ~/.npmrc，项目级 .npmrc 优先级更高。

npm install -g nrm
nrm ls
nrm use npmmirror
nrm test

7.2 国内源

名称	地址
npmmirror	`https://skimdb.npmjs.com/registry/`
npm 官方	`https://registry.npmjs.org/`

registry.npm.taobao.org 已废弃，请用 npmmirror。

7.3 项目级 `.npmrc`（三者通用）

registry=https://skimdb.npmjs.com/registry/
@mycompany:registry=http://npm.company.com/
//npm.company.com/:_authToken=${NPM_TOKEN}

Yarn Berry 还可在 .yarnrc.yml 写 npmRegistryServer（见 5.5 节）。

八、推荐工作流：从 0 到团队规范

8.1 个人新机一条龙

Windows 建议： 首次验证用 CMD 或 Git Bash；若 PowerShell 报「禁止运行脚本」，见 10.2.1。

# 1. Node 版本
nvm install 版本号 && nvm alias default 版本号

# 2. 包管理器（Corepack 一次启用，按项目自动切 pnpm/Yarn）
corepack enable

# 3. 镜像
npm i -g nrm && nrm use npmmirror

# 4. 克隆项目 —— 看 lock 文件决定用谁
git clone xxx && cd xxx
nvm use
# 有 pnpm-lock.yaml  → pnpm install
# 有 yarn.lock       → yarn install
# 有 package-lock.json → npm ci
pnpm dev   # 或 yarn dev / npm run dev

# Windows 验证 PATH（可选）
# where node && where npm

8.2 团队仓库应提交的文件

文件	npm	pnpm	Yarn Berry
`.nvmrc`	✅	✅	✅
`package.json` + `engines`	✅	✅	✅
`package-lock.json`	✅	❌	❌
`pnpm-lock.yaml`	❌	✅	❌
`yarn.lock` + `.yarnrc.yml`	❌	❌	✅
`.yarn/`（Berry 缓存/插件）	❌	❌	常提交
`pnpm-workspace.yaml`	❌	monorepo ✅	❌
`.npmrc`	可选	推荐	推荐

8.3 CI 示例（三种写法）

pnpm：

- run: corepack enable
- run: pnpm install --frozen-lockfile
- run: pnpm build

Yarn Berry：

- run: corepack enable
- run: yarn install --immutable
- run: yarn build

npm：

- run: npm ci
- run: npm run build

九、命令速查表

# ── nvm ──
nvm install 26.5.1 && nvm use 26.5.1 && nvm alias default 26.5.1

# ── npm ──
npm i | npm i pkg -D | npm run dev | npm ci

# ── pnpm ──
pnpm i | pnpm add vue | pnpm -r build | pnpm i --frozen-lockfile

# ── Yarn ──
yarn | yarn add vue | yarn workspace app dev | yarn install --immutable

# ── nrm ──
nrm ls | nrm use npmmirror | nrm test

# ── 诊断（装上了但跑不起来时先跑这些）──
node -v && npm -v && pnpm -v && yarn -v
where node          # Windows：看所有 node 路径
where npm
where pnpm
echo %PATH%         # Windows CMD
$env:Path           # Windows PowerShell
which -a node       # macOS / Linux
npm config get prefix
npm config get registry

十、常见报错与踩坑（重点）

10.1 nvm 相关

坑 1：`nvm: command not found`

处理： 检查 ~/.zshrc / ~/.bashrc 是否有 nvm 初始化块，执行 source ~/.zshrc。

坑 2：`nvm use` 无效，仍是系统 Node

处理： which -a node，卸载非 nvm 的 Node 安装，或调整 PATH 顺序。

坑 3：切换 Node 后全局命令没了

处理： 用 Corepack 管 pnpm/Yarn；CLI 用 npx / pnpm dlx / yarn dlx。

坑 4：Windows symlink 失败

处理： 管理员终端；路径避免中文、空格、OneDrive。

10.2 安装成功但命令跑不起来（PATH / 执行策略 / 终端）

典型现象： 安装程序显示 Success，node -v 却提示「不是内部或外部命令」；或 npm install 成功，但 npm run dev / pnpm / corepack 报 禁止运行脚本、找不到命令。

这类问题不是包装失败，而是 PATH 没配对、PowerShell 拦截脚本，或 多套 Node 抢 PATH。按下面顺序排查。

10.2.1 Windows：PowerShell 禁止执行脚本（最高频）

报错示例：

npm : 无法加载文件 C:\Program Files\nodejs\npm.ps1，因为在此系统上禁止运行脚本。
有关详细信息，请参阅 about_Execution_Policies ...

或 pnpm / yarn / corepack 的 .ps1 / .cmd 类似提示。

原因： Windows 默认 ExecutionPolicy 为 Restricted 或 AllSigned，PowerShell 会拦截 npm 等自带的 .ps1 包装脚本（实际会优先调 .ps1 而非 .cmd）。

解决策略（任选其一，推荐 ① 或 ②）：

① 改用 CMD 或 Git Bash（最快验证）

Win + R → cmd → node -v && npm -v

若在 CMD 里正常、PowerShell 里不行，基本就是执行策略问题。

② 仅对当前用户放宽策略（常用、可长期用）

以普通用户打开 PowerShell（不必管理员）：

Set-ExecutionPolicy -Scope CurrentUser RemoteSigned
# 确认后重开终端
node -v
npm -v

RemoteSigned：本地脚本可运行，网络下载脚本需签名——对日常开发足够。

③ 单次绕过（临时）

powershell -ExecutionPolicy Bypass -Command "npm -v"

④ 在 PowerShell 配置文件里只对 npm 目录放行（进阶）

适合公司策略锁死、不能改 ExecutionPolicy 的机器——优先仍用 CMD / Git Bash。

⑤ 不要用「以管理员运行 npm」作为常态——权限过大，且治不了 PATH 错乱。

VS Code / Cursor 终端： 默认 shell 若是 PowerShell，会在 IDE 里复现该问题。可在设置里把默认终端改为 Command Prompt 或 Git Bash，或按 ② 改 CurrentUser 策略。

10.2.2 PATH 没生效：装上了但 `node` 找不到

报错示例：

'node' 不是内部或外部命令，也不是可运行的程序或批处理文件。

原因 checklist：

原因	说明
安装后未重开终端	安装程序改 PATH，旧窗口读不到
多套 Node 冲突	官方 MSI、nvm-windows、Scoop、Volta 同时存在
nvm-windows 未 `nvm use`	已 install 但未切换，symlink 未指向当前版本
PATH 顺序错误	前面的旧 `node` 抢先
用户 PATH vs 系统 PATH	装到用户目录但终端只读了系统 PATH

排查步骤（Windows）：

# 1. 看系统认哪个 node（多条说明冲突）
where.exe node
where.exe npm

# 2. 看当前 PATH（找 nodejs、nvm、AppData\npm 等）
$env:Path -split ';' | Select-String -Pattern 'node|nvm|npm|pnpm|corepack'

# 3. nvm-windows 用户
nvm list
nvm use 26.5.1
where.exe node    # 应指向 nvm 的 symlink 目录

处理建议：

关掉所有终端 / IDE，重新打开再试
只保留一种 Node 来源：若用 nvm-windows，从「应用和功能」卸载官方 Node MSI，避免双轨
nvm-windows 安装后执行：

nvm install 26.5.1
nvm use 26.5.1
nvm on

手动核对环境变量（Win + R → sysdm.cpl → 高级 → 环境变量）：

变量	典型正确值（nvm-windows）
`NVM_HOME`	`C:\Users\<你>\AppData\Local\nvm`
`NVM_SYMLINK`	`C:\nvm4w\nodejs`（安装时可选路径）
`Path` 中含	`%NVM_HOME%`、`%NVM_SYMLINK%`

npm 全局 bin 不在 PATH（全局装的 CLI 找不到）：

npm config get prefix
# 把 <prefix> 和 <prefix>\node_modules\.bin 或 npm 提示的路径加入用户 Path
# 常见：C:\Users\<你>\AppData\Roaming\npm

10.2.3 Corepack / pnpm / Yarn：enable 了仍找不到命令

现象： corepack enable 无报错，但 pnpm -v 提示不是命令。

处理：

corepack enable
corepack prepare pnpm@latest-10 --activate
where.exe pnpm

确认 Node 的安装目录在 PATH 最前（Corepack 的 shim 在 Node 同目录）
PowerShell 下若报脚本策略，回到 10.2.1
若曾 npm i -g pnpm，与 Corepack 冲突时：卸载全局 pnpm，只留 Corepack

npm uninstall -g pnpm
corepack enable pnpm

10.2.4 macOS / Linux：PATH 与 shell 配置

现象： nvm install 成功，node 仍 command not found。

处理：

# 1. 是否加载 nvm
command -v nvm || echo "nvm 未加载"

# 2. 检查初始化是否写在当前 shell 配置里
grep nvm ~/.zshrc ~/.bashrc 2>/dev/null

# 3. 手动加载后试
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh"
nvm use 26.5.1
which -a node

# 4. Homebrew node 与 nvm 冲突：brew uninstall node，只留 nvm

Apple Silicon 注意： 部分老教程 PATH 写在 .bash_profile 但终端用 zsh，应写在 ~/.zshrc。

10.2.5 安装成功、能跑 node，但 `npm run xxx` 失败

报错类型	常见原因	处理
`'vite' 不是内部或外部命令`	依赖没装完 / 没用 `npm run`	先 `pnpm i`；脚本用 `npm run dev` 不要直接 `vite`
`Permission denied`	脚本无执行权限（Unix）	`chmod +x node_modules/.bin/*` 或重装依赖
`.ps1 禁止运行`	PowerShell 策略	见 10.2.1
`ELIFECYCLE` / exit code 1	业务脚本错误，不是 PATH	看脚本上方真实报错，别只盯 npm 最后一行

10.2.6 推荐：新机 Windows 最小验证清单

按顺序执行，哪一步失败就停在哪一步查：

:: 1. 基础 Node（CMD 里测，排除 PowerShell 策略干扰）
node -v
npm -v

:: 2. nvm-windows（若使用）
nvm list
nvm use 26.5.1
where node

:: 3. Corepack + pnpm
corepack enable
pnpm -v

:: 4. 项目内
cd your-project
pnpm install
pnpm dev

PowerShell 专用验证：

Get-ExecutionPolicy -List
Set-ExecutionPolicy -Scope CurrentUser RemoteSigned
npm -v

10.2.7 策略对照：哪种终端用什么

终端	执行策略问题	PATH 刷新	建议
CMD	无 `.ps1` 拦截	新开窗口生效	排查首选
PowerShell	常中招	新开窗口生效	设 `RemoteSigned` 或换 CMD
Git Bash	一般无	新开窗口	前端日常友好
VS Code 集成终端	继承默认 shell	改设置后重启 IDE	与 ①② 同步处理

10.3 npm 相关

坑 5：`ERESOLVE unable to resolve dependency tree`

处理： 对齐 peer 版本；临时 npm install --legacy-peer-deps（勿长期使用）。

坑 6：`npm ci` 失败 lock 不同步

处理： 本地 npm install 重新生成 lock 并提交。

坑 7：安装极慢 / 超时

处理： nrm use npmmirror 或项目 .npmrc 写 registry。

10.4 pnpm 相关

坑 8：`ERR_PNPM_PEER_DEP_ISSUES`

处理： pnpm add 补全 peer；或 .npmrc 设 auto-install-peers=true。

坑 9：`Cannot find module`（幽灵依赖）

处理： pnpm add xxx 显式声明；临时 shamefully-hoist=true。

坑 10：`ERR_PNPM_OUTDATED_LOCKFILE`

处理： 本地 pnpm install 更新 lock 后提交。

坑 11：Windows `EPERM` / 硬链接失败

处理： 杀毒白名单；.npmrc 设 node-linker=hoisted。

10.5 Yarn 相关

坑 12：Yarn 1 和 Yarn 4 命令/行为不一致

现象： 网上教程写 yarn upgrade，Berry 里是 yarn up；Berry 默认 PnP 无 node_modules。

处理： yarn -v 确认大版本；Berry 项目读 Yarn 4 文档；需要兼容老工具时 .yarnrc.yml 设 nodeLinker: node-modules。

坑 13：`This package doesn't seem to be present in your lockfile`

原因： Berry 严格模式；lock 与 package.json 不一致。

处理：

yarn install              # 本地更新 lock
git add yarn.lock
# CI 用 yarn install --immutable

坑 14：PnP 下 ESLint / TS 报找不到插件

原因： Plug'n'Play 模式下 IDE/工具未配置 PnP SDK。

处理：

yarn dlx @yarnpkg/sdks vscode   # 生成编辑器 SDK

或改用 nodeLinker: node-modules。

坑 15：`Corepack` 与全局 `yarn` 版本冲突

处理：

npm uninstall -g yarn
corepack enable
corepack prepare yarn@stable --activate

坑 16：Yarn 1 项目误用 Berry 安装

现象： 多出 .yarnrc.yml、.yarn/、lock 格式大变，全仓挂掉。

处理： 回滚 git；确认 README/packageManager；Yarn 1 项目继续 yarn install（Classic），勿随意 corepack use yarn@4。

10.6 nrm / 镜像 / 协作

坑 17：nrm 切了源还是慢

处理： 查项目 .npmrc、.yarnrc.yml 是否覆盖；pnpm config get registry。

坑 18：淘宝旧地址失效

处理： 改为 https://registry.npmmirror.com。

坑 19：同一仓库两套 lock

处理： 团队定一种包管理器，删多余 lock，README 写清安装命令。

坑 20：「本地能跑 CI 不行」

检查： Node 版本、包管理器与 lock 类型、是否 --immutable/npm ci、native 模块 OS 差异。

坑 21：`node-gyp` 编译失败

处理（Windows）： Visual Studio Build Tools + Python；优先用带 prebuild 的包。

坑 22：路径含中文导致失败

处理： 项目路径用英文（如 D:\dev\my-app）。

10.7 报错速查表

报错关键词	最可能原因	优先尝试
`不是内部或外部命令` / `node 无法识别`	PATH 未生效 / 多 Node 冲突	重开终端；`where node`；nvm `use`
`禁止运行脚本` / `npm.ps1` / `Execution_Policies`	PowerShell 执行策略	CMD 验证；`Set-ExecutionPolicy -Scope CurrentUser RemoteSigned`
`command not found: nvm`	shell 未加载 nvm	`source ~/.zshrc`
`ERESOLVE`	npm peer 冲突	对齐版本 / `--legacy-peer-deps`
`ERR_PNPM_PEER`	pnpm peer 缺失	`pnpm add` 补 peer
`ERR_PNPM_OUTDATED_LOCKFILE`	pnpm lock 过期	`pnpm i` 后提交 lock
`Cannot find module`	幽灵依赖 / 未安装	显式 `add` 依赖
`lockfile would have been modified`	Yarn `--immutable` 下 lock 变了	本地 `yarn` 后提交 lock
`This package doesn't seem to be present in your lockfile`	Yarn Berry lock 不同步	`yarn install` 更新 lock
PnP / `qualifiedPathToName`	Yarn PnP 工具未适配	`nodeLinker: node-modules` 或 `@yarnpkg/sdks`
`403` / `401`	认证 / registry	`npm login`、查 token
`ETIMEDOUT`	网络 / 源	`nrm use npmmirror`
`gyp ERR`	缺编译环境	VS Build Tools / Xcode CLI

十一、总结

层级	工具	你要记住的
运行时	nvm	多版本 Node，项目用 `.nvmrc`
包管理	npm / pnpm / Yarn	看 lock 文件跟项目走；新建优先 pnpm
版本对齐	Corepack	`packageManager` 字段锁 pnpm/Yarn 版本
网络	nrm / .npmrc	国内 npmmirror，公司源写进项目配置

选型再简记一遍：

跟项目 lock 走 > 新建用 pnpm > 小 demo 用 npm > 已有 Yarn Berry 继续 Yarn

配好 nvm + Corepack + nrm 后，日常就是：

nvm use && pnpm i && pnpm dev   # 或 yarn / npm，取决于仓库

遇到报错，先看 10.7 速查表；装上了但 node/npm 跑不起来，直接查 10.2 PATH 与执行策略。

参考链接

nvm：https://github.com/nvm-sh/nvm
nvm-windows：https://github.com/coreybutler/nvm-windows
npm 文档：https://docs.npmjs.com/
pnpm 文档：https://pnpm.io/
Yarn 文档：https://yarnpkg.com/
Yarn 迁移指南：https://yarnpkg.com/migration/guide
Corepack：https://github.com/nodejs/corepack
npmmirror：https://npmmirror.com/
nrm：https://github.com/Pana/nrm

posted @ 2026-08-03 09:47 幼儿园技术家阅读(3) 评论(0) 收藏举报

刷新页面返回顶部

zxlh1529

前进，加油！！！

前端 Node 全家桶

前言：为什么需要这一套 nvm + npm + pnpm + Yarn + nrm？

一、nvm：Node 版本管理

1.1 是什么？

1.2 安装（macOS / Linux）

1.3 常用命令

1.4 项目级版本锁定：.nvmrc

1.5 常见问题

二、包管理器总览：npm / pnpm / Yarn 怎么选？

2.1 三者一句话

2.2 核心指标对照表

2.3 命令对照表（日常开发）

2.4 按场景选型：该用哪个？（参考表）

2.5 混用禁忌

三、npm：Node 自带的包管理器

3.1 核心文件

3.2 常用命令

3.3 npm vs npx

四、pnpm：更快、更省磁盘

4.1 安装

4.2 Monorepo 示例

4.3 .npmrc 常用配置

4.4 从 npm / Yarn 迁移到 pnpm

五、Yarn：Classic 与 Berry（Yarn 4）

5.1 版本区分

5.2 安装 Yarn 4（Berry）

5.3 常用命令（Berry）

5.4 Monorepo（Yarn workspaces）

5.5 .yarnrc.yml 常见配置

5.6 Yarn 1 → Yarn 4 迁移提示

六、Corepack：统一管理 npm / pnpm / Yarn 版本

七、nrm：镜像源一键切换

7.1 是什么？

7.2 国内源

7.3 项目级 .npmrc（三者通用）

八、推荐工作流：从 0 到团队规范

8.1 个人新机一条龙

8.2 团队仓库应提交的文件

8.3 CI 示例（三种写法）

九、命令速查表

十、常见报错与踩坑（重点）

10.1 nvm 相关

坑 1：nvm: command not found

坑 2：nvm use 无效，仍是系统 Node

坑 3：切换 Node 后全局命令没了

坑 4：Windows symlink 失败

10.2 安装成功但命令跑不起来（PATH / 执行策略 / 终端）

10.2.1 Windows：PowerShell 禁止执行脚本（最高频）

10.2.2 PATH 没生效：装上了但 node 找不到

10.2.3 Corepack / pnpm / Yarn：enable 了仍找不到命令

10.2.4 macOS / Linux：PATH 与 shell 配置

10.2.5 安装成功、能跑 node，但 npm run xxx 失败

10.2.6 推荐：新机 Windows 最小验证清单

10.2.7 策略对照：哪种终端用什么

10.3 npm 相关

坑 5：ERESOLVE unable to resolve dependency tree

坑 6：npm ci 失败 lock 不同步

坑 7：安装极慢 / 超时

10.4 pnpm 相关

坑 8：ERR_PNPM_PEER_DEP_ISSUES

坑 9：Cannot find module（幽灵依赖）

坑 10：ERR_PNPM_OUTDATED_LOCKFILE

坑 11：Windows EPERM / 硬链接失败

10.5 Yarn 相关

坑 12：Yarn 1 和 Yarn 4 命令/行为不一致

坑 13：This package doesn't seem to be present in your lockfile

坑 14：PnP 下 ESLint / TS 报找不到插件

坑 15：Corepack 与全局 yarn 版本冲突

坑 16：Yarn 1 项目误用 Berry 安装

10.6 nrm / 镜像 / 协作

坑 17：nrm 切了源还是慢

坑 18：淘宝旧地址失效

坑 19：同一仓库两套 lock

坑 20：「本地能跑 CI 不行」

坑 21：node-gyp 编译失败

坑 22：路径含中文导致失败

10.7 报错速查表

十一、总结

1.4 项目级版本锁定：`.nvmrc`

4.3 `.npmrc` 常用配置

5.5 `.yarnrc.yml` 常见配置

7.3 项目级 `.npmrc`（三者通用）

坑 1：`nvm: command not found`

坑 2：`nvm use` 无效，仍是系统 Node

10.2.2 PATH 没生效：装上了但 `node` 找不到

10.2.5 安装成功、能跑 node，但 `npm run xxx` 失败

坑 5：`ERESOLVE unable to resolve dependency tree`

坑 6：`npm ci` 失败 lock 不同步

坑 8：`ERR_PNPM_PEER_DEP_ISSUES`

坑 9：`Cannot find module`（幽灵依赖）

坑 10：`ERR_PNPM_OUTDATED_LOCKFILE`

坑 11：Windows `EPERM` / 硬链接失败

坑 13：`This package doesn't seem to be present in your lockfile`

坑 15：`Corepack` 与全局 `yarn` 版本冲突

坑 21：`node-gyp` 编译失败