cnpm 常用命令

cnpm 是淘宝 NPM 镜像的客户端工具，是 npm 的中国版，命令与 npm 完全一致，只是默认使用淘宝镜像源，解决国内安装依赖慢的问题。

---

安装

# 全局安装（指定淘宝镜像源安装）
npm install -g cnpm --registry=https://registry.npmmirror.com

# 查看版本
cnpm -v

# 查看安装路径（Linux/macOS）
which cnpm

---

与 npm 的关系

cnpm 的命令和 npm 完全一致，只是默认指向淘宝镜像源：

对比项	npm	yarn	pnpm	cnpm
镜像源	https://registry.npmjs.org	https://registry.yarnpkg.com	https://registry.npmjs.org	https://registry.npmmirror.com
命令	npm install	yarn install	pnpm install	cnpm install
锁文件	package-lock.json	yarn.lock	pnpm-lock.yaml	package-lock.json（7.x 起支持，9.x 完全兼容）
维护方	npm Inc.	Meta（原 Facebook）	Zoltan Kochan	淘宝团队
安装速度（国内）	慢	中等	快	快
磁盘占用	大	大	小（硬链接）	大
幽灵依赖	存在	存在	不存在	存在

💡 如果只是想加速 npm，推荐直接修改 npm 镜像源，不一定需要安装 cnpm。

---

常用命令

cnpm 的命令与 npm 完全一致，以下列出最常用的：

四种依赖类型说明

类型	安装命令	说明	大白话解释	使用场景
dependencies	cnpm install <pkg>	生产环境依赖	项目运行必须用到的包	vue、react、axios、lodash 等
devDependencies	cnpm install -D <pkg>	开发环境依赖	只在开发时用，打包后不需要	vite、eslint、typescript、jest 等
peerDependencies	cnpm install -P <pkg>	对等依赖	你的包「期望」使用者自己安装的依赖	组件库期望使用者已安装 vue
optionalDependencies	cnpm install -O <pkg>	可选依赖	安装失败不会报错，项目照样能跑	跨平台兼容包、性能优化包

安装依赖

# 安装所有依赖（根据 package-lock.json）
cnpm install
cnpm i                        # 简写，效果一样

# 安装指定包（添加到 dependencies）
cnpm install <package>
cnpm i <package>

# 安装指定包（添加到 devDependencies）
# -D 是 --save-dev 的简写，表示只在开发环境使用
cnpm install -D <package>
cnpm i -D <package>

# 安装指定版本
cnpm i <package>@1.2.3

# 安装最新版本
cnpm i <package>@latest

# 全局安装
# -g 是 --global 的简写，全局安装的包可以在任何地方使用命令
cnpm install -g <package>

# 安装并保存到 peerDependencies
# -P 是 --save-peer 的简写
cnpm install -P <package>

# 安装并保存到 optionalDependencies
# -O 是 --save-optional 的简写
cnpm install -O <package>

卸载 & 更新

# 卸载指定包
cnpm uninstall <package>
cnpm rm <package>             # 简写

# 更新指定包（遵守版本范围）
cnpm update <package>

# 更新所有依赖（不加包名，更新 package.json 中所有依赖）
cnpm update

# 全局卸载
cnpm uninstall -g <package>

查看信息

# 查看包信息（版本、依赖、仓库、作者等）
cnpm info <package>
cnpm view <package>

# 列出已安装的包（树形结构）
cnpm list
cnpm ls                       # 简写

# 列出顶层依赖（不显示嵌套的子依赖）
# --depth 控制显示层级，0 表示只显示顶层
cnpm ls --depth=0

# 查看为什么安装了某个包（显示依赖链）
cnpm why <package>

运行脚本

# 运行 package.json 中的脚本
cnpm run <script-name>

# 常见脚本
cnpm run dev                  # 启动开发服务器
cnpm run build                # 构建生产版本
cnpm test                     # 运行测试

# 传递参数给脚本（-- 分隔符）
# - `--` 是参数分隔符，用于区分 cnpm 本身的参数和脚本的参数
# - `--` 之后的所有参数都会传递给脚本
cnpm run build -- --mode production
cnpm test -- --watch

# 可以传递多个参数
cnpm run build -- --mode production --verbose

# 常见工具参数示例：

# Vite 构建工具：
cnpm run dev -- --port 3001       # 指定开发服务器端口
cnpm run dev -- --host            # 允许外部访问（局域网其他设备可访问）
cnpm run build -- --mode staging  # 指定构建模式（staging 是预发布环境）
cnpm run build -- --outDir dist2  # 指定输出目录

# ESLint 代码检查：
cnpm run lint -- --fix            # 自动修复可修复的问题
cnpm run lint -- --ext .js,.ts    # 指定检查的文件扩展名（ESLint 9+ 已废弃此参数）
cnpm run lint -- --no-error-on-unmatched-pattern  # 无匹配文件时不报错

# Vitest 测试框架：
cnpm test -- --watch              # 监听模式，文件变化时重新测试
cnpm test -- --coverage           # 生成测试覆盖率报告
cnpm test -- --reporter verbose   # 使用详细报告器
cnpm test -- --bail 1             # 第一个测试失败后停止

# TypeScript 编译器：
cnpm run build -- --noEmit        # 只检查类型，不输出文件（常用于类型检查）
cnpm run build -- --sourceMap     # 生成 source map（调试时定位源码）
cnpm run build -- --watch         # 监听模式，文件变化时自动编译

📖 创建自定义脚本的详细方法请参考 npm 常用命令

其他命令

# 搜索包（按关键词搜索 npm 上的包）
cnpm search <keyword>

# 清除缓存（--force 表示强制执行，不提示确认）
cnpm cache clean --force

# 查看配置
cnpm config list

# 发布包（发布到 npm，不是淘宝镜像）
cnpm publish

# 同步包到淘宝镜像（cnpm 独有，用于强制同步最新版本）
cnpm sync <package>

# 查看哪些包有新版本
cnpm outdated

# 检查环境配置是否正常（cnpm 独有）
cnpm doctor

---

代理配置

# 设置 HTTP 代理
cnpm config set proxy http://127.0.0.1:7890

# 设置 HTTPS 代理
cnpm config set https-proxy http://127.0.0.1:7890

# 取消代理
cnpm config delete proxy
cnpm config delete https-proxy

---

CI/CD 安装

# CI/CD 环境推荐使用 npm ci（精确安装）
# cnpm 没有 ci 命令，建议在 CI/CD 中使用 npm ci + 镜像源配置
npm ci --registry=https://registry.npmmirror.com

为什么 CI/CD 推荐用 npm ci？

特性	npm ci	cnpm install
lock 文件	严格按 lock 安装，不修改	可能更新 lock 文件
node_modules	先删除再安装	增量安装
速度	更快	较慢
适用场景	CI/CD、自动化	本地开发

通俗解释：

• npm ci：严格安装，完全按照 lock 文件安装，不更新任何文件，适合 CI/CD 环境确保一致性
• cnpm install：智能安装，会根据 package.json 自动更新 lock 文件，适合本地开发

---

缓存管理

# 查看缓存目录路径
cnpm config get cache

# 清除所有缓存（--force 表示强制执行，不提示确认）
cnpm cache clean --force

# 验证缓存完整性（检查缓存是否损坏）
cnpm cache verify

缓存的作用

• 提升安装速度：已下载的包会缓存，下次安装直接从缓存读取
• 离线安装：有缓存时可以离线安装（部分场景）
• 减少网络请求：避免重复下载相同的包

什么时候需要清理缓存？

• 安装失败且提示缓存相关错误
• 缓存占用空间过大
• 切换镜像源后需要清理旧缓存

---

cnpm 的局限性

锁文件兼容性

cnpm 从 7.x 开始支持生成 package-lock.json，9.x 已完全兼容 npm 的锁文件格式。但 6.x 及更早版本不生成锁文件，如果使用旧版本：

• 不同时间安装可能得到不同版本的依赖
• 团队成员的依赖版本可能不一致
• CI/CD 环境无法保证一致性

部分命令可能有差异

某些 npm 的新特性 cnpm 可能支持较慢。

官方推荐迁移

cnpm 官方建议关注 npmmirror 的最新动态，推荐使用原生 npm/yarn/pnpm 配合镜像源使用。

---

更推荐的方式：直接配置 npm 镜像

与其安装 cnpm，更推荐直接修改 npm 的镜像源，这样仍然使用 npm 命令，同时享受国内加速：

# 方式一：修改 npm 配置（永久生效）
npm config set registry https://registry.npmmirror.com

# 方式二：使用 nrm 管理多个镜像源（推荐，可快速切换）
npm install -g nrm
nrm ls                        # 查看可用镜像源
nrm use taobao                # 切换到淘宝镜像

# 方式三：项目级 .npmrc（只对当前项目生效）
echo 'registry=https://registry.npmmirror.com' > .npmrc

修改后，所有 npm install 都会自动走淘宝镜像。

如需恢复官方源：

# 恢复 npm 官方源
npm config set registry https://registry.npmjs.org

# 或通过 nrm 切换
nrm use npm

---

使用 nrm 管理镜像源

nrm 是一个 npm 镜像源管理工具，可以快速切换不同的镜像。详见 nrm 常用命令。

# 安装 nrm
npm install -g nrm

# 切换到淘宝镜像
nrm use taobao

# 切换回官方源
nrm use npm

---

常见问题

cnpm 和 npm 混用导致问题

混用 cnpm 和 npm 可能出现以下症状：

• node_modules 中的依赖版本与 package-lock.json 不一致
• 运行时报找不到模块（Cannot find module）
• 同一项目不同成员安装的依赖版本不同
• 构建产物在不同环境下行为不一致

原因：cnpm 和 npm 的依赖解析策略、缓存目录、锁文件写入方式存在差异。

建议：选定一个包管理器后不要混用。如果已经混用：

# 清理后重新安装
rm -rf node_modules
rm package-lock.json       # 如果锁文件已损坏
npm install                # 用 npm 重新生成 lock 文件

# 或切换到 pnpm（推荐，速度快、磁盘省）
rm -rf node_modules
rm package-lock.json
pnpm install               # pnpm 会生成 pnpm-lock.yaml

项目中已配置 .npmrc

如果项目中已有 .npmrc 文件配置了镜像源，不需要额外使用 cnpm：

# .npmrc
registry=https://registry.npmmirror.com

此时直接用 npm install 即可。

cnpm 安装后命令找不到

# 检查全局安装路径
npm config get prefix

# 确保路径在 PATH 中（Linux/macOS）
export PATH=$(npm config get prefix)/bin:$PATH

# 或使用 npx 代替（临时使用）
npx cnpm install

cnpm 安装的包在 npm 中看不到

cnpm 和 npm 使用不同的缓存目录，但依赖都安装在同一个 node_modules 中，一般不影响使用。

# 查看各自的缓存目录
npm config get cache
cnpm config get cache

---

推荐的包管理器选择

场景	推荐	原因
国内开发	pnpm + npmmirror 镜像	速度快、磁盘省、无幽灵依赖
已有 npm 项目	npm + npmmirror 镜像	兼容性好
Monorepo	pnpm	原生工作空间支持
需要兼容旧项目	npm	最稳定

💡 使用 pnpm + 淘宝镜像时，node-sass 等包含二进制文件的包需要额外配置二进制镜像：

# .npmrc
sass_binary_site=https://npmmirror.com/mirrors/node-sass

不推荐使用 cnpm 的原因：

• 旧版本（6.x 及以下）不生成锁文件，依赖不可控（7.x 起已改善）
• 与 npm/pnpm/yarn 混用容易出问题
• 直接配置镜像源即可达到同样效果

---

参考

• 淘宝 NPM 镜像
• cnpm GitHub