SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场npm-check-updates

npm-check-updates

编程与开发

查看项目

更新于 10-15 14:34

技能介绍

npm-check-updates（ncu）用于把 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 中的版本提升到可用的最新版本（试运行、交互式或写入磁盘）。
  • 使用过滤器、拒绝列表、peer 依赖感知或引擎约束进行批量升级。
  • 扫描 monorepo（workspaces、--deep、自定义 glob）。
  • 通过冷却窗口或迭代式 --doctor 模式进行更安全的升级。
  • 从 Node 脚本或 .ncurc.* 配置以编程方式驱动 ncu。

快速开始

试运行：打印升级项，不修改文件。

ncu

将升级写回 package.json，然后安装。

ncu -u npm install

交互式选择要升级的包。

ncu -i

只处理部分包。

ncu -f "react,react-dom" ncu "/^@types//"

只提升 patch / minor 版本。

ncu --target patch ncu --target minor

跳过某个包。

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 天、12h 小时、30m 分钟。用于缓解供应链风险。
  • --peer：选择版本时遵守 peer 依赖约束。
  • --enginesNode：只考虑与项目 engines.node 兼容的版本。
  • --deep：递归处理 cwd 下的每个 package.json。
  • -w, --workspaces：对每个 workspace 操作（npm、yarn、pnpm）。配合 --no-root 可排除根项目。
  • --workspace <s>：对指定的 workspace 操作。配合 --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：在指定 workspace 之外同时包含根项目。
  • --stdin：从 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, // 写回磁盘 })

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

所有 workspace，包括根项目。

ncu -uw

cwd 下的所有 package.json 文件。

ncu --deep -u

特定 glob，合并根配置。

ncu --packageFile 'packages/*/package.json' --mergeConfig -u

自定义注册表 / 私有镜像

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

或托管在任何位置的静态 JSON 目录。

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。它有时在等待 stdin。
  • 未给出 --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 需要注册表时间数据。某些镜像不提供。如果没有任何报告，请使用公共注册表。

验证速查

显示所有 CLI 选项。

ncu --help

单个参数的扩展帮助。

ncu --help --filter ncu --help --target ncu --help --cooldown ncu --help --doctor