npm-check-updates

npm-check-updates (ncu)

npm-check-updates 会将 package.json 中的依赖升级到最新版本，同时保留现有的版本范围策略（^17.0.2 → ^18.3.1）。它只会修改 package.json；用户必须运行包管理器的安装命令（例如 npm install）来更新 package-lock.json 和 node_modules。

CLI 命令为 npm-check-updates，也可以使用较短的 ncu。该库是纯 ESM，可从 Node 导入（也可通过 require() 从 CommonJS 加载）。

何时使用此工具

• 列出项目中过时的依赖。
• 将 package.json 中的版本升级到最新版本（可先试运行、交互操作或直接写入磁盘）。
• 使用筛选条件、拒绝列表、对等依赖感知或引擎约束，批量升级依赖。
• 扫描 monorepo（工作区、--deep、自定义 glob）。
• 通过冷却期或迭代式 --doctor 模式，更安全地升级依赖。
• 通过 Node 脚本或 .ncurc.* 配置，以编程方式运行 ncu。

快速开始

# Dry run: print upgrades without touching files.
ncu

# Write the upgrades back into package.json, then install.
ncu -u
npm install

# Interactively pick which packages to upgrade.
ncu -i

# Only a subset of packages.
ncu -f "react,react-dom"
ncu "/^@types\//"

# Bump only patch / minor versions.
ncu --target patch
ncu --target minor

# Skip a package.
ncu -x typescript,eslint

重要标志

标志	用途
-u, --upgrade	覆盖 package.json（非试运行模式下必须设置）。
-i, --interactive	从清单中选择软件包。除非设置了 JSON 输出，否则隐含 -u。
-t, --target <value>	latest（默认）、newest、greatest、minor、patch、semver 或 @<tag>（例如 @next、@beta）。
-f, --filter <p>	仅包含匹配的名称。接受字符串、通配符、glob、逗号或空格分隔的列表、/regex/，或谓词（在 .ncurc.js 中）。
-x, --reject <p>	排除匹配的名称。匹配语法与 --filter 相同。位置参数支持 ! 前缀（ncu \!nodemon）。
-g, --global	检查全局安装的软件包，而不是本地项目中的软件包。
-p, --packageManager <s>	npm、yarn、pnpm、deno、bun 或 staticRegistry。
-d, --doctor	逐个安装并测试每项升级，以定位不兼容变更。需要设置 -u。
-c, --cooldown <period>	跳过在指定时间窗口内发布的版本。7 / 7d 表示 7 天，12h 表示 12 小时，30m 表示 30 分钟。降低供应链风险。
--peer	选择版本时遵循 peer 依赖约束。
--enginesNode	仅考虑与项目的 engines.node 兼容的版本。
--deep	递归查找当前工作目录下的所有 package.json。
-w, --workspaces	对所有工作区（npm、yarn、pnpm）执行操作。与 --no-root 配合可排除根目录。
--workspace <s>	对指定的工作区执行操作。与 --no-root 配合可排除根目录。
--packageFile <p>	覆盖默认的 package.json 位置。接受 glob（packages/*/package.json）。
-j, --jsonAll	输出新的完整 package.json。
--jsonDeps	与 --jsonAll 类似，但仅包含依赖字段。
--jsonUpgraded	以 JSON 格式输出已升级的依赖项。
--format <value>	逗号分隔的列表：dep、group、ownerChanged、repo、time、lines、installedVersion、cooldown。
-l, --loglevel <n>	silent、error、minimal、warn（默认）、info、verbose、silly。
-e, --errorLevel <n>	1（默认）或 2。2 适用于 CI：无需更新时退出码为 0。
--cache	缓存注册表查询。默认文件：~/.ncu-cache.json。默认 TTL：10 分钟。
--cacheFile <path>	缓存文件路径。
--cacheExpiration <min>	缓存 TTL（分钟）。
--registry <uri>	自定义注册表。
--registryType <type>	npm（默认）或 json（静态 JSON 目录）。
--install <value>	always、never 或 prompt（默认）。在 -u 后运行安装？
--pre <n>	包含预发布版本。使用 --target newest 或 greatest 时，以及当前版本为预发布版本时，会自动启用。
--minimal	如果当前版本范围已满足 semver 意义上的最新版本，则跳过升级。
--removeRange	移除版本范围运算符，并固定到确切版本。
--timeout <ms>	全局超时时间。每个请求的默认值：30 秒。
--retry <n>	注册表请求失败时的重试次数（默认：3）。
--doctorInstall <cmd>	覆盖 --doctor 使用的安装命令。
--doctorTest <cmd>	覆盖 --doctor 使用的测试命令。
--mergeConfig	与 --deep 或 glob 配合时，将找到的每个配置与根配置合并。
--root	将根项目与指定的工作区一并包含。
--stdin	从标准输入读取 package.json。
--packageData <value>	将 package.json 内容作为字符串传入。

配置文件（.ncurc.*）

ncu 会从以下位置读取配置（后面的配置会覆盖前面的配置）：CLI 标志 → 本地 .ncurc.* → 项目 .ncurc.* → $HOME/.ncurc.*。

支持的文件类型：.ncurc、.ncurc.json、.ncurc.yaml、.ncurc.yml、.ncurc.js、.ncurc.mjs、.ncurc.cjs。

从 v21 起，项目采用纯 ESM，因此 .ncurc.js 应使用 ESM export default；CJS 配置必须使用 .cjs。

.ncurc.js 也是唯一可以使用谓词函数的地方，例如：

export default {
  filter: name => !name.startsWith('internal-'),
  reject: ['@types/*'],
  target: 'minor',
  cooldown: 7,
  doctor: false,
}

编程式 API

import ncu from 'npm-check-updates'

const upgraded = await ncu({
  packageFile: './packages/app/package.json',
  filter: ['react', 'react-dom'],
  target: 'latest',
  upgrade: true, // write back to disk
})

console.log(upgraded) // { 'react': '^18.3.1', 'react-dom': '^18.3.1' }

使用 Node 直接运行：

node ./scripts/check-deps.ts

推荐工作流

最稳妥的升级路径

1. 确保已提交工作树中的更改。
2. 运行 ncu --cooldown 7，跳过最近发布的版本。
3. 运行 ncu -u，写入更新。
4. 运行 npm install（或当前包管理器对应的命令）。
5. 运行测试套件；如果通过，则提交更改。

自动检测有破坏性的升级

ncu --doctor -u

逐一回退有问题的升级，并打印出导致问题的包。

Monorepo

# All workspaces, including the root.
ncu -uw

# All packages.json files under the cwd.
ncu --deep -u

# A specific glob, merging root config.
ncu --packageFile 'packages/*/package.json' --mergeConfig -u

自定义注册表／私有镜像

ncu --registry https://npm.example.com --packageManager npm

# Or a static JSON catalog hosted anywhere.
ncu --registry https://example.com/versions.json --registryType json

易错点和注意事项

• ncu 只会写入 package.json。更新锁文件和 node_modules 需要单独执行安装步骤。
• --doctor 会修改锁文件和 node_modules。请使用干净的工作树。
• 默认 CLI 名称 ncu 在某些系统上会与 ncu-weather-cli 和 Nvidia CUDA 的 ncu 冲突。如果输出异常，请改用 npm-check-updates。
• 在 Windows 上，如果 ncu 看起来卡住了，建议使用 --packageFile package.json。它有时是在等待标准输入。
• 如果未指定 --cooldown，冷却时长会从 min-release-age（npm）、npmMinimalAgeGate（yarn）或 pnpm-workspace.yaml 中的 minimumReleaseAge（pnpm）读取。
• 从 v21.0.0 起采用纯 ESM。.ncurc.js 必须使用 ESM（export default）；CJS 配置需要使用 .cjs 扩展名。
• --format cooldown 需要注册表时间数据。有些镜像不会公开这些数据。如果没有报告结果，请使用公共注册表。

验证速查表

# Show all CLI options.
ncu --help

# Extended help for a single flag.
ncu --help --filter
ncu --help --target
ncu --help --cooldown
ncu --help --doctor