本文整理
npm-check-updates（简称 ncu）从入门到实战的全部常用命令，一站式解决项目依赖检查、升级、筛选、配置等场景，适用于 Node.js 项目，复制即用。
前言
npm-check-updates 是前端/后端项目依赖版本管理神器，核心作用：
- 检查
package.json中依赖的最新版本 - 仅修改版本号，不直接安装依赖（区别于
npm update） - 支持筛选生产/开发依赖、交互式升级、自定义规则等高级能力
- 兼容 npm/yarn/pnpm，是项目发版、依赖升级必备工具
一、全局安装
# 全局安装 npm-check-updates
npm install -g npm-check-updates
# 验证安装成功（查看版本）
ncu -v
二、基础核心命令（90% 场景使用）
1. 检查依赖更新（最常用）
仅展示可更新的依赖，不修改任何文件
ncu
2. 升级 package.json 版本号
将依赖版本更新为最新，不执行安装
ncu -u
# 全称
ncu --upgrade
3. 检查 + 升级 + 一键安装
升级版本号后，自动执行包安装命令
# npm
ncu -u && npm install
# pnpm（推荐）
ncu -u && pnpm install
# yarn
ncu -u && yarn install
三、筛选依赖（精准升级）
1. 仅升级 生产依赖（dependencies）
ncu -u --prod
2. 仅升级 开发依赖（devDependencies）
ncu -u --dev
3. 仅升级指定包
ncu -u react react-dom
4. 排除指定包（不升级）
ncu -u -x lodash axios
# 全称
ncu -u --exclude lodash axios
四、版本规则控制
1. 仅升级小版本/补丁（不升级大版本）
# 仅升级 patch (1.0.0 → 1.0.1)
ncu -u --patch
# 仅升级 minor (1.0.0 → 1.1.0)
ncu -u --minor
# 升级所有版本（默认）
ncu -u --major
2. 锁定版本格式（去除 ^/~ 符号）
ncu -u --semver-level exact
五、交互式升级（手动选择）
可视化界面，手动勾选需要升级的依赖（安全推荐）
ncu -i
# 全称
ncu --interactive
六、高级输出格式
1. JSON 格式输出（便于脚本处理）
ncu --json
2. 生成 Markdown 格式报告
ncu --markdown
3. 查看详细更新日志
ncu --verbose
七、全局依赖检查/升级
管理全局安装的 npm 包
# 检查全局依赖更新
ncu -g
# 升级全局依赖
ncu -u -g
八、配置文件（批量复用规则）
项目根目录创建 .ncurc.json，无需每次输入参数：
{
"upgrade": true,
"prod": true,
"exclude": ["lodash", "dayjs"],
"minor": true
}
直接执行命令即可自动应用配置：
ncu
九、CI/自动化场景
1. 检查是否有可更新依赖（无输出则无更新）
ncu --error-level 2
2. 忽略预发布版本（仅升级稳定版）
ncu -u --stable
十、常用命令速查表
| 命令 | 作用 |
|---|---|
ncu | 检查可更新依赖 |
ncu -u | 升级 package.json 版本 |
ncu -i | 交互式选择升级 |
ncu --prod | 仅升级生产依赖 |
ncu --dev | 仅升级开发依赖 |
ncu -x 包名 | 排除指定依赖 |
ncu -g | 检查全局依赖 |
ncu --minor | 仅升级次版本 |
十一、常见问题
- ncu 和 npm update 区别？
ncu：修改package.json为最新版本，不安装npm update：安装新版本，不修改版本号
- 升级后项目报错？
建议使用
ncu -i交互式升级，避免大版本破坏性更新 - 支持 monorepo 项目吗？
支持，进入子包目录执行
ncu即可
总结
npm-check-updates 是项目依赖管理的效率工具，核心记住 3 个命令即可覆盖日常：
ncu：检查更新ncu -u：升级版本号ncu -i：安全交互式升级
配合包管理器一键安装，彻底告别手动修改依赖版本的繁琐操作 🚀
