前端 Node 全家桶

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

刚入门前端时,常见困惑是:

  1. 项目 A 要 Node 16,项目 B 要 Node 20,本机只能装一个?
  2. npm install 慢、占磁盘、node_modules 巨大?
  3. npm、pnpm、Yarn 到底用哪个?锁文件能不能混?
  4. 公司内网 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)

bash 复制代码
# 官方安装脚本(版本号以官网为准)
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 常用命令

bash 复制代码
# 查看可安装版本
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:

text 复制代码
22.23.2

进入目录后:

bash 复制代码
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 写清:

text 复制代码
本项目使用 pnpm,请勿使用 npm/yarn install。
安装:corepack enable && pnpm install

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

3.1 核心文件

text 复制代码
my-app/
├── package.json
├── package-lock.json
└── node_modules/

3.2 常用命令

bash 复制代码
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,不必全局安装
bash 复制代码
npx create-vue@latest my-vue-app

四、pnpm:更快、更省磁盘

4.1 安装

bash 复制代码
corepack enable pnpm
pnpm -v

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

4.2 Monorepo 示例

pnpm-workspace.yaml:

yaml 复制代码
packages:
  - 'packages/*'
  - 'apps/*'

子包引用:

json 复制代码
{
  "dependencies": {
    "ui": "workspace:*"
  }
}
bash 复制代码
pnpm install
pnpm --filter web dev
pnpm -r build

4.3 .npmrc 常用配置

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

4.4 从 npm / Yarn 迁移到 pnpm

bash 复制代码
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)

bash 复制代码
corepack enable
corepack prepare yarn@stable --activate
yarn -v

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

package.json:

json 复制代码
{
  "packageManager": "yarn@4.9.1"
}

5.3 常用命令(Berry)

bash 复制代码
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:

json 复制代码
{
  "private": true,
  "workspaces": ["packages/*", "apps/*"]
}
bash 复制代码
yarn install
yarn workspace web dev
yarn workspaces foreach run build

5.5 .yarnrc.yml 常见配置

yaml 复制代码
# 国内镜像(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 造成版本混乱:

bash 复制代码
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 优先级更高。

bash 复制代码
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(三者通用)

ini 复制代码
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。

bash 复制代码
# 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:

yaml 复制代码
- run: corepack enable
- run: pnpm install --frozen-lockfile
- run: pnpm build

Yarn Berry:

yaml 复制代码
- run: corepack enable
- run: yarn install --immutable
- run: yarn build

npm:

yaml 复制代码
- run: npm ci
- run: npm run build

九、命令速查表

bash 复制代码
# ── 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。

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


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

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

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

10.2.1 Windows:PowerShell 禁止执行脚本(最高频)

报错示例:

text 复制代码
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(最快验证)

text 复制代码
Win + R → cmd → node -v && npm -v

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

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

以普通用户打开 PowerShell(不必管理员):

powershell 复制代码
Set-ExecutionPolicy -Scope CurrentUser RemoteSigned
# 确认后重开终端
node -v
npm -v

RemoteSigned:本地脚本可运行,网络下载脚本需签名------对日常开发足够。

③ 单次绕过(临时)

powershell 复制代码
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 找不到

报错示例:

text 复制代码
'node' 不是内部或外部命令,也不是可运行的程序或批处理文件。

原因 checklist:

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

排查步骤(Windows):

powershell 复制代码
# 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 目录

处理建议:

  1. 关掉所有终端 / IDE,重新打开再试
  2. 只保留一种 Node 来源:若用 nvm-windows,从「应用和功能」卸载官方 Node MSI,避免双轨
  3. nvm-windows 安装后执行:
cmd 复制代码
nvm install 26.5.1
nvm use 26.5.1
nvm on
  1. 手动核对环境变量 (Win + R → sysdm.cpl → 高级 → 环境变量):
变量 典型正确值(nvm-windows)
NVM_HOME C:\Users\<你>\AppData\Local\nvm
NVM_SYMLINK C:\nvm4w\nodejs(安装时可选路径)
Path 中含 %NVM_HOME%、%NVM_SYMLINK%
  1. npm 全局 bin 不在 PATH(全局装的 CLI 找不到):
cmd 复制代码
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 提示不是命令。

处理:

cmd 复制代码
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
cmd 复制代码
npm uninstall -g pnpm
corepack enable pnpm

10.2.4 macOS / Linux:PATH 与 shell 配置

现象: nvm install 成功,node 仍 command not found。

处理:

bash 复制代码
# 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 最小验证清单

按顺序执行,哪一步失败就停在哪一步查:

cmd 复制代码
:: 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 专用验证:

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 不一致。

处理:

bash 复制代码
yarn install              # 本地更新 lock
git add yarn.lock
# CI 用 yarn install --immutable

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

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

处理:

bash 复制代码
yarn dlx @yarnpkg/sdks vscode   # 生成编辑器 SDK

或改用 nodeLinker: node-modules。

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

处理:

bash 复制代码
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,公司源写进项目配置

选型再简记一遍:

text 复制代码
跟项目 lock 走 > 新建用 pnpm > 小 demo 用 npm > 已有 Yarn Berry 继续 Yarn

配好 nvm + Corepack + nrm 后,日常就是:

bash 复制代码
nvm use && pnpm i && pnpm dev   # 或 yarn / npm,取决于仓库

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


参考链接

相关推荐
deli0076 小时前
TCP 为什么会粘包?4 种拆包方案 49 字节实测对比
前端
deli0077 小时前
32K 上下文塞满后,AI 最先忘掉什么?120 轮对话实测
前端
deli0078 小时前
手机拍灯为什么有一条条黑纹?PWM 240Hz 实测
前端
wangruofeng13 小时前
AI Models 1.1.0 发布,查大模型价格、对比模型和找 API 地址
前端·aigc·ai编程
wangruofeng13 小时前
给前端开发者的 100 个设计参考网站
前端·设计
星栈16 小时前
视频即代码,Remotion 能做什么、不能做什么
前端·音视频开发
广州华水科技16 小时前
单北斗GNSS位移监测系统的应用与技术解析
前端
用户479492835691516 小时前
从一句话或代码仓到可交互 HTML:开源 Agent 画图技能 Archify v3.2 实测与选型边界
前端·后端·面试
风骏时光牛马19 小时前
生成一个AI多模态标题,仅输出一条标题,无额外文字、问句、备选、配图、文案等任何附加内容,不需要其他的任务服务 只要标题。
前端
wangruofeng19 小时前
从 GIF 到 AVIF:网页图片格式演进与 2026 年选型指南
前端·架构