npm & Yarn 换源、常用命令与故障完整手册

2023/3/6·14 views

说明：原文章信息老旧（含废弃taobao域名、缺少Yarn2/PnP、link、workspace、二进制镜像、权限根治方案），本文基于原文完整扩充、修正过时内容，补充高频开发场景、故障排查、命令对照表。

前言

Node.js 默认从国外官方源下载依赖，网络差时极易超时、卡顿、安装失败。国内开发统一使用 npmmirror 淘宝镜像（旧域名 registry.npm.taobao.org 已永久废弃，切勿使用）。本文覆盖 npm、Yarn Classic(1.x)、Yarn Berry(2/3/4) 全场景命令、镜像配置、本地联调link、缓存管理、权限/编译报错解决方案。

一、npm 全套操作指南

1. 镜像源切换（核心，2026有效地址）

1.1 临时单次安装使用国内源

仅本次安装生效，不修改全局配置

bash 复制代码

npm install 包名 --registry=https://registry.npmmirror.com

1.2 全局永久设置镜像（推荐）

bash 复制代码

# 设置淘宝镜像
npm config set registry https://registry.npmmirror.com

# 还原官方源（发布包、校验原版依赖时使用）
npm config set registry https://registry.npmjs.org

1.3 手动配置 .npmrc 文件

配置优先级：项目目录 .npmrc > 用户目录 ~/.npmrc > Node全局配置

项目根目录新建/编辑 .npmrc
写入：

ini 复制代码

registry=https://registry.npmmirror.com
# 二进制包镜像（解决node-sass、electron下载失败）
sass_binary_site=https://npmmirror.com/mirrors/node-sass/
electron_mirror=https://npmmirror.com/mirrors/electron/

1.4 校验源是否生效

bash 复制代码

# 查看当前registry
npm config get registry
# 打印全部npm配置
npm config list
# 测试拉取包信息验证连通性
npm info lodash

1.5 cnpm 工具（阿里封装npm，仅本地调试用）

避坑：React-Native 项目禁止使用cnpm，模块软链接结构异常会导致打包器报错

bash 复制代码

# 全局安装cnpm
npm install -g cnpm --registry=https://registry.npmmirror.com
# 验证
cnpm -v
# 使用方式和npm完全一致
cnpm install axios

2. npm 依赖安装/卸载/更新

bash 复制代码

# 安装项目全部依赖（读取package.json）
npm install
# 安装生产依赖（dependencies）
npm install axios
# 安装开发依赖（devDependencies）
npm install vite --save-dev / npm install vite -D
# 指定版本安装
npm install vue@3.4.0
# 全局安装工具
npm install -g pino
# 仅安装生产依赖（CI/服务器部署）
npm install --production
# 跳过脚本执行（解决node-sass编译报错）
npm install --ignore-scripts

# 卸载依赖
npm uninstall axios
# 卸载全局包
npm uninstall -g cnpm

# 更新依赖
npm update
# 更新指定包
npm update vue
# 更新全局工具
npm update -g npm

3. npm link 本地联调（补充原文缺失）

npm 1.0+ 全版本支持，用于本地开发组件库/SDK，实现软链接调试

bash 复制代码

# 1. 进入你的组件库目录，全局注册软链接
cd ./lib-package
npm link

# 2. 业务项目关联本地包
cd ./web-project
npm link lib-package

# 取消本地链接，恢复线上版本
npm unlink lib-package
# 清理全局链接
npm unlink -g lib-package

4. 全局目录、缓存、脚本运行

bash 复制代码

# 查看全局包存放路径
npm root -g
# 查看当前项目本地bin目录
npm bin

# 查看全局安装包（仅展示一级依赖）
npm list -g --depth=0
# 查看项目所有依赖树
npm list

# 运行package.json脚本
npm run dev
npm run build

# 缓存管理
npm cache clean --force # 强制清空缓存（解决下载异常）
npm cache verify # 校验缓存完整性，清理损坏文件

5. npx 临时执行包（补充）

无需全局安装，临时调用工具

bash 复制代码

npx create-next-app@latest

二、Yarn 全套操作指南（区分Yarn1 Classic / Yarn2+ Berry）

1. Yarn 安装方式

Windows

powershell 复制代码

# Chocolatey
choco install yarn
# Scoop
scoop install yarn
# npm全局安装
npm install -g yarn

MacOS

bash 复制代码

brew install yarn

2. Yarn 镜像源配置

bash 复制代码

# 设置淘宝源
yarn config set registry https://registry.npmmirror.com
# 查看当前源
yarn config get registry
# 查看全部配置
yarn config list
# 还原官方源
yarn config set registry https://registry.npmjs.org

3. 依赖管理命令

yarn add 安装依赖

bash 复制代码

# 生产依赖
yarn add axios
# 开发依赖
yarn add vite -D / yarn add vite --dev
# 指定版本
yarn add vue@3.4
# 全局工具
yarn global add typescript

yarn install 安装项目依赖

bash 复制代码

# 完整安装所有依赖
yarn install
# 仅安装生产依赖（CI部署）
yarn install --production
# 严格锁定lock文件，不更新版本（线上打包必用）
yarn install --frozen-lockfile
# Yarn2+切换node_modules模式（关闭PnP）
# .yarnrc.yml 添加 nodeLinker: node-modules

卸载、更新、查看依赖

bash 复制代码

# 卸载依赖，自动更新package.json/yarn.lock
yarn remove axios

# 更新全部依赖
yarn upgrade
# 仅更新指定包
yarn upgrade vue
# 查看依赖树，depth=0只展示一级依赖
yarn list --depth=0
# 匹配关键字查看包
yarn list --pattern vue

4. 缓存、全局路径、脚本运行

bash 复制代码

# 查看全局缓存目录
yarn cache dir
# 按匹配规则列出缓存包
yarn cache list --pattern gulp
# 清空全部缓存
yarn cache clean

# 运行脚本（可省略run）
yarn run dev / yarn dev
# 查看全局二进制文件路径
yarn global bin
# 列出全局安装包
yarn global list

5. Yarn dlx 临时执行包（等同npx）

bash 复制代码

yarn dlx create-next-app

三、npm / Yarn 高频报错完整解决方案

3.1 权限报错 EACCES（Mac/Linux）、管理员权限不足（Windows）

现象

全局安装、创建文件夹时报权限拒绝

方案1：临时提权（不推荐长期）

bash 复制代码

# Mac/Linux
sudo npm install -g xxx
# Windows：右键以管理员打开终端执行命令
npm install
# 跳过权限校验
npm install -g xxx --unsafe-perm

方案2：根治（推荐，修改npm全局目录归属）

bash 复制代码

# Mac/Linux
sudo chown -R $USER ~/.npm
sudo chown -R $USER /usr/local/lib/node_modules
# 自定义npm全局目录
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc
source ~/.zshrc

3.2 node-sass / node-gyp 编译失败、缺少Python2

原因

缺少编译工具链（python、vs build tools、xcode）
二进制文件下载超时
Node版本与node-sass不兼容

修复步骤

设置sass二进制镜像

bash 复制代码

npm config set sass_binary_site https://npmmirror.com/mirrors/node-sass/

Windows安装编译工具

powershell 复制代码

npm install -g windows-build-tools

Mac安装编译工具

bash 复制代码

xcode-select --install

跳过安装脚本临时修复

bash 复制代码

npm i --ignore-scripts

长期方案：替换sass（dart-sass）替代废弃node-sass

3.3 切换镜像后下载依旧慢/失败

清理缓存

bash 复制代码

npm cache clean --force
yarn cache clean

检查项目 .npmrc 是否写死旧官方源，覆盖全局配置
关闭SSL校验（网络特殊环境）

bash 复制代码

npm config set strict-ssl false

3.4 Yarn2+ 安装后无node_modules（PnP模式）

Yarn Berry 默认PnP零安装模式，无node_modules目录，部分旧构建工具不兼容

切换为传统node_modules模式

项目根目录创建/修改 .yarnrc.yml

yaml 复制代码

nodeLinker: node-modules

重新执行安装：

bash 复制代码

yarn install

3.5 duplicate key 主键冲突（PostgreSQL联动补充）

配套开发常见问题：导入数据后自增序列落后，同步blogs_id_seq

sql 复制代码

-- 自动同步序列到表最大id
SELECT setval('blogs_id_seq', COALESCE((SELECT MAX(id) FROM blogs), 0));

四、npm / Yarn 常用命令对照表（速查）

操作场景	npm	Yarn Classic(1.x)
安装依赖	npm install	yarn install
安装生产包	npm i axios	yarn add axios
安装开发包	npm i -D vite	yarn add vite -D
卸载包	npm uninstall axios	yarn remove axios
更新包	npm update vue	yarn upgrade vue
全局安装	npm i -g xxx	yarn global add xxx
运行脚本	npm run dev	yarn dev / yarn run dev
清理缓存	npm cache clean --force	yarn cache clean
查看全局包	npm list -g --depth=0	yarn global list
临时执行包	npx pkg	yarn dlx pkg
本地联调link	npm link	yarn link
锁定版本安装	npm ci	yarn install --frozen-lockfile

五、开发最佳实践总结

统一镜像：所有项目强制配置 npmmirror.com，废弃旧taobao域名；
禁止全局依赖泛滥：业务依赖全部本地安装，仅工具类全局；
CI打包：使用 npm ci / yarn install --frozen-lockfile，严格锁定版本；
原生编译包：提前配置sass、electron二进制镜像，避免构建失败；
本地组件调试：使用 npm link 实现实时联调，无需重复发包；
权限规避：Mac/Linux优先修改npm目录归属，少用sudo；
Yarn2+项目：老脚手架兼容场景切换nodeLinker模式，避免PnP报错。

对这篇文章有意见或建议？提交反馈