npm-check-updates 最全用法合集

本文整理 npm-check-updates （简称 ncu）从入门到实战的全部常用命令，一站式解决项目依赖检查、升级、筛选、配置等场景，适用于 Node.js 项目，复制即用。

前言

npm-check-updates 是前端/后端项目依赖版本管理神器，核心作用：

检查 package.json 中依赖的最新版本
仅修改版本号，不直接安装依赖 （区别于 npm update）
支持筛选生产/开发依赖、交互式升级、自定义规则等高级能力
兼容 npm/yarn/pnpm，是项目发版、依赖升级必备工具

一、全局安装

bash 复制代码

# 全局安装 npm-check-updates
npm install -g npm-check-updates

# 验证安装成功（查看版本）
ncu -v

二、基础核心命令（90% 场景使用）

1. 检查依赖更新（最常用）

仅展示可更新的依赖，不修改任何文件

bash 复制代码

ncu

2. 升级 package.json 版本号

将依赖版本更新为最新，不执行安装

bash 复制代码

ncu -u
# 全称
ncu --upgrade

3. 检查 + 升级 + 一键安装

升级版本号后，自动执行包安装命令

bash 复制代码

# npm
ncu -u && npm install

# pnpm（推荐）
ncu -u && pnpm install

# yarn
ncu -u && yarn install

三、筛选依赖（精准升级）

1. 仅升级生产依赖（dependencies）

bash 复制代码

ncu -u --prod

2. 仅升级开发依赖（devDependencies）

bash 复制代码

ncu -u --dev

3. 仅升级指定包

bash 复制代码

ncu -u react react-dom

4. 排除指定包（不升级）

bash 复制代码

ncu -u -x lodash axios
# 全称
ncu -u --exclude lodash axios

四、版本规则控制

1. 仅升级小版本/补丁（不升级大版本）

bash 复制代码

# 仅升级 patch (1.0.0 → 1.0.1)
ncu -u --patch

# 仅升级 minor (1.0.0 → 1.1.0)
ncu -u --minor

# 升级所有版本（默认）
ncu -u --major

2. 锁定版本格式（去除 ^/~ 符号）

bash 复制代码

ncu -u --semver-level exact

五、交互式升级（手动选择）

可视化界面，手动勾选需要升级的依赖（安全推荐）

bash 复制代码

ncu -i
# 全称
ncu --interactive

六、高级输出格式

1. JSON 格式输出（便于脚本处理）

bash 复制代码

ncu --jsonAll

2. 查看详细更新日志

bash 复制代码

ncu --verbose

七、全局依赖检查/升级

管理全局安装的 npm 包

bash 复制代码

# 检查全局依赖更新
ncu -g

# 升级全局依赖
ncu -u -g

八、配置文件（批量复用规则）

项目根目录创建 .ncurc.json，无需每次输入参数：

json 复制代码

{
  "upgrade": true,
  "prod": true,
  "exclude": ["lodash", "dayjs"],
  "minor": true
}

直接执行命令即可自动应用配置：

bash 复制代码

ncu

九、CI/自动化场景

1. 检查是否有可更新依赖（无输出则无更新）

bash 复制代码

ncu --errorLevel 2

2. 忽略预发布版本（仅升级稳定版）

bash 复制代码

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：安全交互式升级

配合包管理器一键安装，彻底告别手动修改依赖版本的繁琐操作 🚀

npm-check-updates 最全用法合集

前言

一、全局安装

二、基础核心命令（90% 场景使用）

1. 检查依赖更新（最常用）

2. 升级 package.json 版本号

3. 检查 + 升级 + 一键安装

三、筛选依赖（精准升级）

1. 仅升级 生产依赖（dependencies）

2. 仅升级 开发依赖（devDependencies）

3. 仅升级指定包

4. 排除指定包（不升级）

四、版本规则控制

1. 仅升级小版本/补丁（不升级大版本）

2. 锁定版本格式（去除 ^/~ 符号）

五、交互式升级（手动选择）

六、高级输出格式

1. JSON 格式输出（便于脚本处理）

2. 查看详细更新日志

七、全局依赖检查/升级

八、配置文件（批量复用规则）

九、CI/自动化场景

1. 检查是否有可更新依赖（无输出则无更新）

2. 忽略预发布版本（仅升级稳定版）

十、常用命令速查表

十一、常见问题

总结

1. 仅升级生产依赖（dependencies）

2. 仅升级开发依赖（devDependencies）