npm-check-updates

npm-check-updates 会将 package.json 中的依赖项升级到 最新 版本，忽略指定的版本。

• 保持现有的语义化版本 策略，即 "react": "^18.3.1" 到 "react": "^19.2.7"。
• 仅 修改 package.json 文件。运行 npm install 以更新已安装的包和 package-lock.json。
• 合理的默认设置，但高度可定制
• 兼容 npm、yarn、pnpm、deno 和 bun
• 支持 CLI 和模块使用
• 纯 ESM，也可通过 require() 从 CommonJS 中使用

$${\color{red}红色}$$ 主要版本升级（以及所有 主要版本为零)
$${\color{cyan}青色}$$ 次要版本升级
$${\color{green}绿色}$$ 补丁版本升级

要求

• Node.js: ^22.22.2 || ^24.15.0 || >=26.0.0
• npm: >=10.0.0

安装

全局安装以使用 npm-check-updates 或更短的 ncu：

npm install -g npm-check-updates

或使用 npx（仅支持长格式）：

npx npm-check-updates

用法

检查所有项目依赖项的最新版本：

$ ncu
Checking package.json
[====================] 5/5 100%

 eslint             7.32.0  →    8.0.0
 prettier           ^2.7.1  →   ^3.0.0
 svelte            ^3.48.0  →  ^3.51.0
 typescript         >3.0.0  →   >4.0.0
 untildify          <4.0.0  →   ^4.0.0
 webpack               4.x  →      5.x

Run ncu -u to upgrade package.json

升级项目的包文件：

请确保您的包文件已纳入版本控制，且所有更改均已提交。此操作_将_覆盖您的包文件。

$ ncu -u
Upgrading package.json
[====================] 1/1 100%

 express           4.12.x  →   4.13.x

Run npm install to install new versions.

$ npm install      # update installed packages and package-lock.json

检查全局包：

ncu -g

交互模式

在交互模式下选择要更新的软件包：

ncu --interactive
ncu -i

搭配 --format group 打造真正 奢华 的体验：

按键

• ↑↓ 选择一个包
• Space 切换选择
• a 切换全选
• Enter 升级

过滤包

使用 --filter 选项或添加额外的 cli 参数来过滤包：

# upgrade only mocha
ncu mocha
ncu -f mocha
ncu --filter mocha

# upgrade only chalk, mocha, and react
ncu chalk mocha react
ncu chalk, mocha, react
ncu -f "chalk mocha react"

使用通配符或正则表达式进行过滤：

# upgrade packages that start with "react-"
ncu react-*
ncu "/^react-.*$/"

使用 --reject 选项或在过滤器前添加 ! 来排除特定软件包。支持字符串、通配符、globs、逗号或空格分隔的列表以及正则表达式：

# upgrade everything except nodemon
ncu \!nodemon
ncu -x nodemon
ncu --reject nodemon

# upgrade packages that do not start with "react-".
ncu \!react-*
ncu '/^(?!react-).*$/' # mac/linux
ncu "/^(?!react-).*$/" # windows

高级过滤器：filter, filterResults, filterVersion

如何确定依赖项更新

• 直接依赖项将更新到最新的稳定版本：
  • 2.0.1 → 2.2.0
  • 1.2 → 1.3
  • 0.1.0 → 1.0.1
• 保留范围运算符并更新版本：
  • ^1.2.0 → ^2.0.0
  • 1.x → 2.x
  • >0.2.0 → >0.3.0
• “小于”将被替换为通配符：
  • <2.0.0 → ^3.0.0
  • 1.0.0 < 2.0.0 → ^3.0.0
• 保留“任意版本”：
  • * → *
• 默认情况下忽略预发布版本。
  • 使用 --pre 以包含预发布版本（例如 alpha, beta, build1235）
• 选择要升级到的级别：
  • 使用 --target semver，根据您指定的 semver 版本范围进行更新：
    • ^1.1.0 → ^1.9.99
    • 显式的上限将被尊重并保留，因此升级永远不会超过该上限：
      • ^9.5.0 <10 → ^9.7.0 <10
  • 使用 --target minor，严格更新补丁版本和次要版本（包括主版本为零的情况）：
    • 0.1.0 → 0.2.1
  • 使用 --target patch，严格更新补丁版本（包括主版本为零的情况）：
    • 0.1.0 → 0.1.2
  • 使用 --target @next，更新到 next 标签上发布的版本：
    • 0.1.0 -> 0.1.1-next.1

选项

选项按以下优先级合并：

1. 命令行选项
2. 本地 Config File（当前工作目录）
3. 项目 Config File（位于 package.json 旁边）
4. 用户 Config File（$HOME）

不接受参数的选项可以通过在前面添加 --no- 来取反，例如 --no-peer。

--cache	将版本缓存到本地缓存文件。默认 --cacheFile 为 ~/.ncu-cache.json，默认 --cacheExpiration 为 10 分钟。
--cacheClear	清除默认缓存，或 --cacheFile 指定的缓存文件。
--cacheExpiration <min>	缓存过期时间（分钟）。仅与 --cache 配合使用。（默认值：10）
--cacheFile <path>	缓存文件的路径。仅与 --cache 配合使用。（默认值："~/.ncu-cache.json"）
--color	强制在终端中显示颜色。
--concurrency <n>	对 registry 的最大并发 HTTP 请求数。（默认值：8）
--configFileName <s>	配置文件名称。（默认值：.ncurc 或 .ncurc.{json,yaml,yml,js,mjs,cjs}）
--configFilePath <path>	.ncurc 配置文件的目录。（默认值：packageFile 的目录）
-c, --cooldown <period>	设置被视为可升级的包版本的最小年龄。接受数字（天）或带单位的字符串："7d"（天）、"12h"（小时）、"30m"（分钟）。降低安装新发布且可能存在风险的包的风险。
--cwd <path>	npm 将执行的工作目录。
--deep	在当前工作目录中递归运行。是 (--packageFile '**/package.json') 的别名。
--dep <value>	仅检查一个或多个依赖项部分：dev、optional、peer、prod 或 packageManager（以逗号分隔）。(默认值: ["prod","dev","optional","packageManager"])
--deprecated	包含已弃用的包。使用 --no-deprecated 排除已弃用的包（速度降低 20–25%）。(默认值: true)
-d, --doctor	迭代地安装升级并运行测试，以识别破坏性升级。需要 -u 才能执行。
--doctorInstall <command>	指定在 doctor 模式下使用的安装脚本。(默认值: npm install 或您的包管理器的等效命令)
--doctorTest <command>	指定在 doctor 模式下使用的测试脚本。(默认值: npm test)
--enginesNode	仅包含满足包文件中指定的 engines.node 的包。
-e, --errorLevel <n>	设置错误级别。1：如果没有发生错误，则以错误代码 0 退出。2：如果没有需要更新的包，则以错误代码 0 退出（适用于持续集成）。（默认值：1）
-f, --filter <p>	仅包含匹配给定字符串、通配符、glob、逗号或空格分隔的列表、/regex/ 或谓词函数的包名称。
filterResults <fn>	在获取新版本后，根据用户提供的谓词函数过滤结果。
--filterVersion <p>	使用逗号或空格分隔的列表或 /regex/ 按包版本进行过滤。
--format <value>	修改输出格式或显示附加信息。指定一个或多个逗号分隔的值：dep, group, ownerChanged, repo, time, lines, installedVersion, cooldown。 group 是唯一默认包含的值；使用 --format no-group 可禁用它。（默认值：["group"]）
-g, --global	检查全局包，而不是当前项目中的包。
groupFunction <fn>	自定义在使用 --format group 时包如何分组。
--install <value>	控制自动安装行为：always、never、prompt。（默认值："prompt"）
-i, --interactive	为每个依赖项启用交互式提示；除非设置了某个 json 选项，否则隐含 -u。
-j, --jsonAll	输出新的包文件，而不是人类可读的消息。
--jsonDeps	类似于 jsonAll，但仅列出新包数据中的 dependencies、devDependencies、optionalDependencies 等。
--jsonUpgraded	以 json 格式输出已升级的依赖项。
-l, --loglevel <n>	日志记录量：silent、error、minimal、warn、info、verbose、silly。（默认值："warn"）
--mergeConfig	对于 --deep 或 --packageFile 选项，将嵌套配置与根配置文件合并。（默认值：false）
-m, --minimal	不升级根据 semver 已被版本范围满足的较新版本。
--packageData <value>	包文件数据（也可以使用 stdin）。
--packageFile <path|glob>	包文件位置。（默认值：./package.json）
-p, --packageManager <s>	npm, yarn, pnpm, deno, bun, staticRegistry（默认值：npm）。
--peer	检查已安装包的 peer dependencies，并将更新过滤为兼容版本。
--pre <n>	包含预发布版本，例如 -alpha.0、-beta.5、-rc.2。当 --target 为 newest 或 greatest，或当前版本为预发布版本时，自动设置为 1。（默认值：0）
--prefix <path>	npm 的当前工作目录。
-r, --registry <uri>	指定在查找包版本时使用的 registry。
--registryType <type>	指定 --registry 是指向完整的 npm registry 还是简单的 JSON 文件或 url：npm, json。（默认值：npm）
-x, --reject <p>	排除匹配给定字符串、通配符、glob、逗号或空格分隔的列表、/regex/ 或谓词函数的包。
--rejectVersion <p>	使用逗号或空格分隔的列表或 /regex/ 排除 package.json 版本。
--removeRange	从最终包版本中移除版本范围。
--retry <n>	重试获取包信息的失败请求的次数。(默认值: 3)
--root	除了指定的工作区外，还在根项目上运行更新。仅允许与 --workspace 或 --workspaces 一起使用。(默认值: true)
-s, --silent	不输出任何内容。--loglevel silent 的别名。
--stdin	从标准输入读取 package.json。
-t, --target <value>	确定要升级到的版本: latest, newest, greatest, minor, patch, semver, @[tag], 或 [function]。(默认值: latest)
--timeout <ms>	全局超时时间（毫秒）。(默认值: 无全局超时，每个 npm-registry-fetch 为 30 秒)
-u, --upgrade	用升级后的版本覆盖包文件，而不仅仅是输出到控制台。
--verbose	记录额外的调试信息。--loglevel verbose 的别名。
--workspace <s>	在一个或多个指定的工作区上运行。添加 --no-root 以排除根项目。(默认值: [])
-w, --workspaces	在所有工作区上运行。添加 --no-root 以排除根项目。

高级选项

某些选项具有高级用法，或者允许通过在 .ncurc.js 文件中指定函数来设置按包的值。

运行 ncu --help [OPTION] 以查看特定选项的高级帮助，或参见下文：

cooldown

用法：

ncu --cooldown [period]
ncu -c [period]

冷却选项有助于防范供应链攻击，它要求软件包版本在考虑升级之前，必须至少提前给定的时间量发布。

该值可以是一个纯数字（天数）或带有单位后缀的字符串：

--cooldown 7       7 days
--cooldown 7d      7 days (same as above)
--cooldown 12h     12 hours
--cooldown 30m     30 minutes

使用默认的 --target latest，如果最新的 dist-tag 版本处于冷却窗口内，ncu 将回退到通过冷却阈值检查的最高版本。若要完全跳过该包（严格行为），请使用 --target "@latest"。

示例：

让我们查看冷却机制在一个拥有以下可用版本的包中是如何工作的：

1.0.0          Released 7 days ago    (initial version)
1.1.0          Released 6 days ago    (minor update)
1.1.1          Released 5 days ago    (patch update)
1.2.0          Released 5 days ago    (minor update)
2.0.0-beta.1   Released 5 days ago    (beta release)
1.2.1          Released 4 days ago    (patch update)
1.3.0          Released 4 days ago    (minor update) [latest]
2.0.0-beta.2   Released 3 days ago    (beta release)
2.0.0-beta.3   Released 2 days ago    (beta release) [beta]

使用默认目标（latest）：

ncu --cooldown 5

回退到 1.2.0，原因如下：

• 最新版本（1.3.0）仅发布 4 天（处于 5 天冷却期内）
• 1.2.0 是满足至少 5 天发布时间的最高版本

使用 @latest 严格目标：

ncu --cooldown 5 --target @latest

不会建议更新，原因如下：

• 最新版本 (1.3.0) 仅发布了 4 天
• 冷却期要求版本至少发布 5 天
• @latest 是严格的：不会回退到旧版本

使用 @beta/@tag 目标时：

ncu --cooldown 3 --target @beta

不会建议更新，原因如下：

• 当前 beta（2.0.0-beta.3）仅发布 2 天
• 冷却期要求版本至少发布 3 天
• 使用 --cooldown 2 或更低版本以允许此更新

针对其他目标：

ncu --cooldown 5 --target greatest|newest|minor|patch|semver

每个目标将选择至少 5 天前的最佳版本：

greatest → 1.2.0        (highest version number outside cooldown)
newest   → 2.0.0-beta.1 (most recently published version outside cooldown)
minor    → 1.2.0        (highest minor version outside cooldown)
patch    → 1.1.1        (highest patch version outside cooldown)

你也可以在 .ncurc.js 文件中或作为模块导入 npm-check-updates 时提供自定义函数。

⚠️ 谓词函数仅在 .ncurc.js 中或作为模块导入 npm-check-updates 时可用，在命令行上不可用。要将 JSON 配置转换为 JS 配置，请按照 Config Functions 中的说明操作。

/** Set cooldown to 3 days but skip it for `@my-company` packages.
  @param packageName     The name of the dependency.
  @returns               Cooldown days restriction for given package.
*/
cooldown: packageName => (packageName.startsWith('@my-company') ? 0 : 3)

包管理器配置

如果未显式设置 --cooldown，则 ncu 会自动从包管理器自身的原生配置中读取冷却时间配置——每个包管理器仅参考其自身的配置，且这些配置不会在包管理器之间交叉应用：

npm	从 .npmrc 中读取 min-release-age，排除匹配 min-release-age-exclude 的包。
yarn	从 .yarnrc.yml 中读取 npmMinimalAgeGate，排除匹配 npmPreapprovedPackages 的包。
pnpm	从 pnpm-workspace.yaml 中读取 minimumReleaseAge，排除匹配 minimumReleaseAgeExclude 的包。

冷却时间格式

当使用 --format cooldown 配合 --cooldown 选项时，ncu 将显示因 --cooldown 阈值而被跳过的包列表。

示例：

$ ncu --format cooldown --cooldown 7
Skipped due to 7-day cooldown
 @typescript-eslint/parser  ^8.50.0  →  ^8.59.1      5 days ago
 eslint                     ^10.0.1  →  ^10.3.0      1 day ago

doctor

用法：

ncu --doctor -u
ncu --no-doctor
ncu -du

迭代地安装升级并运行项目的测试，以识别破坏性升级。回滚损坏的升级，并使用可用的升级更新 package.json。

需要 -u 来执行（会修改你的 package 文件、lock 文件以及 node_modules）

更精确地说：

1. 运行 npm install 和 npm test 以确保测试当前通过。
2. 运行 ncu -u 以乐观地升级所有依赖项。
3. 如果测试通过，太好了！
4. 如果测试失败，恢复 package 文件和 lock 文件。
5. 对于每个依赖项，安装升级并运行测试。
6. 打印带有测试错误的损坏升级。
7. 将可用的升级保存到 package.json。

其他选项：

--doctorInstall	指定自定义安装脚本（默认：npm install 或 yarn）
--doctorTest	指定自定义测试脚本（默认：npm test）

示例：

$ ncu --doctor -u
Running tests before upgrading
npm install
npm run test
Upgrading all dependencies and re-running tests
ncu -u
npm install
npm run test
Tests failed
Identifying broken dependencies
npm install
npm install --no-save react@16.0.0
npm run test
  ✓ react 15.0.0 → 16.0.0
npm install --no-save react-redux@7.0.0
npm run test
  ✗ react-redux 6.0.0 → 7.0.0

/projects/myproject/test.js:13
  throw new Error('Test failed!')
  ^

npm install --no-save react-dnd@11.1.3
npm run test
  ✓ react-dnd 10.0.0 → 11.1.3
Saving partially upgraded package.json

filter

用法:

ncu --filter [p]
ncu -f [p]

仅包含与给定字符串、通配符、glob、逗号或空格分隔的列表、/regex/ 或谓词函数匹配的包名称。仅包含的包将使用 --peer 进行检查。

--filter 在新版本获取 之前 运行，而 --filterResults 则在 之后 运行。

您还可以在 .ncurc.js 文件中或作为模块导入 npm-check-updates 时指定自定义函数。

⚠️ 谓词函数仅在 .ncurc.js 中或作为模块导入 npm-check-updates 时可用，在命令行上不可用。要将 JSON 配置转换为 JS 配置，请按照 Config Functions 中的说明操作。

/**
  @param name     The name of the dependency.
  @param semver   A parsed Semver array of the current version.
    (See: https://git.coolaj86.com/coolaj86/semver-utils.js#semverutils-parse-semverstring)
  @returns        True if the package should be included, false if it should be excluded.
*/
filter: (name, semver) => {
  if (name.startsWith('@myorg/')) {
    return false
  }
  return true
}

filterResults

在获取新版本后，根据用户提供的谓词函数过滤结果。

filterResults 在新版本获取 之后 运行，而 filter、reject、filterVersion 和 rejectVersion 则在 之前 运行。这允许你根据版本的变化情况（例如主版本号变更）使用 filterResults 排除某些升级。

⚠️ 谓词函数仅在 .ncurc.js 中或作为模块导入 npm-check-updates 时可用，在命令行中不可用。要将 JSON 配置转换为 JS 配置，请按照 Config Functions 中的说明操作。

/** Exclude major version updates. Note this could also be achieved with --target semver.
  @param {string} packageName               The name of the dependency.
  @param {string} current                   Current version declaration (may be a range).
  @param {SemVer[]} currentVersionSemver    Current version declaration in semantic versioning format (may be a range).
  @param {string} upgraded                  Upgraded version.
  @param {SemVer} upgradedVersionSemver     Upgraded version in semantic versioning format.
  @returns {boolean}                        Return true if the upgrade should be kept; otherwise, it will be ignored.
*/
filterResults: (packageName, { current, currentVersionSemver, upgraded, upgradedVersionSemver }) => {
  const currentMajor = parseInt(currentVersionSemver[0]?.major, 10)
  const upgradedMajor = parseInt(upgradedVersionSemver?.major, 10)
  if (currentMajor && upgradedMajor) {
    return currentMajor >= upgradedMajor
  }
  return true
}

关于 SemVer 类型定义，参见：https://git.coolaj86.com/coolaj86/semver-utils.js#semverutils-parse-semverstring

filterVersion

用法：

ncu --filterVersion [p]

仅包含与给定字符串、通配符、glob、逗号或空格分隔的列表或 /regex/ 匹配的版本。

--filterVersion 在新版本获取 之前 运行，而 --filterResults 则在 之后 运行。

若要使用谓词函数进行过滤，请改用 filter。它会接收包名和解析后的当前版本，因此可以基于名称和版本进行匹配。

format

用法：

ncu --format [value]

默认值：group

修改输出格式或显示附加信息。指定一个或多个以逗号分隔的值。

dep	打印每个包的依赖类型（dev、peer、optional）。
group	按主版本、次版本、修订版本以及主版本为零的更新对包进行分组。
homepage	如果在其 package.json 中指定，则显示指向包主页的链接。
installedVersion	打印确切的当前版本号，而不是版本范围。
lines	在单独的行上打印 name@version。适用于通过管道传递给 npm install。
ownerChanged	显示包的所有者是否已更改。
repo	推断并显示指向包源代码仓库的链接。需要已安装包。
diff	显示用于比较包版本之间更改的链接。
time	显示每次升级的发布时间。
cooldown	显示因 --cooldown 阈值而被跳过的包列表。

group 是唯一默认包含的值。在其前面加上 "no-" 即可将其移除，而不是替换整个列表，例如 --format no-group 用于禁用默认分组。

groupFunction

在使用 --format group 时，自定义包如何划分为组。

仅在 .ncurc.js 中或作为模块导入 npm-check-updates 时可用，在命令行中不可用。要将 JSON 配置转换为 JS 配置，请按照 Config Functions 中的说明操作。

/**
  @param name             The name of the dependency.
  @param defaultGroup     The predefined group name which will be used by default.
  @param currentSpec      The current version range in your package.json.
  @param upgradedSpec     The upgraded version range that will be written to your package.json.
  @param upgradedVersion  The upgraded version number returned by the registry.
  @returns                A predefined group name ('major' | 'minor' | 'patch' | 'majorVersionZero' | 'none') or a custom string to create your own group.
*/
groupFunction: (name, defaultGroup, currentSpec, upgradedSpec, upgradedVersion) => {
  if (name === 'typescript' && defaultGroup === 'minor') {
    return 'major'
  }
  if (name.startsWith('@myorg/')) {
    return 'My Org'
  }
  return defaultGroup
}

安装

用法：

ncu --install [value]

默认值：prompt

控制自动安装行为。

always	升级后自动运行包管理器的安装命令。
never	不安装且不提示。
prompt	升级后显示一条建议安装的消息，但不执行安装。在交互模式下，会提示是否安装。（默认）

packageManager

用法：

ncu --packageManager [s]
ncu -p [s]

指定在查找版本时使用的包管理器。

npm	系统安装的 npm。默认值。
yarn	系统安装的 yarn。如果存在 yarn.lock，则自动使用。
pnpm	系统安装的 pnpm。如果存在 pnpm-lock.yaml，则自动使用。
bun	系统安装的 bun。如果存在 bun.lock 或 bun.lockb，则自动使用。

peer

用法：

ncu --peer
ncu --no-peer

检查已安装包的 peer dependencies，并将更新过滤为兼容版本。

示例：

以下示例演示了 --peer 的工作原理，以及它如何使用升级模块中的 peer dependencies。

包 ncu-test-peer-update 发布了两个版本：

• 1.0.0 具有 peer dependency "ncu-test-return-version": "1.0.x"
• 1.1.0 具有 peer dependency "ncu-test-return-version": "1.1.x"

我们的测试应用具有以下依赖项：

"ncu-test-peer-update": "1.0.0",
"ncu-test-return-version": "1.0.0"

这些软件包的最新版本是：

"ncu-test-peer-update": "1.1.0",
"ncu-test-return-version": "2.0.0"

使用 --peer：

ncu 将包升级到仍符合 peer dependency 约束的最高版本：

ncu-test-peer-update     1.0.0  →  1.1.0
ncu-test-return-version  1.0.0  →  1.1.0

没有 --peer：

作为对比：如果不使用 --peer 选项，ncu 将建议最新版本，忽略 peer dependencies：

ncu-test-peer-update     1.0.0  →  1.1.0
ncu-test-return-version  1.0.0  →  2.0.0

registryType

用法：

ncu --registryType [type]

指定 --registry 是指完整的 npm registry 还是一个简单的 JSON 文件。

npm	默认 npm registry
json	从指向简单 JSON registry 的文件或 url 中检查版本。必须包含 --registry 选项。

示例：

# local file
ncu --registryType json --registry ./registry.json

# url
ncu --registryType json --registry https://api.mydomain/registry.json

# you can omit --registryType when the registry ends in .json
ncu --registry ./registry.json
ncu --registry https://api.mydomain/registry.json

registry.json：

{
  "prettier": "2.7.1",
  "typescript": "4.7.4"
}

拒绝

用法：

ncu --reject [p]
ncu -x [p]

--filter 的反向操作。排除与给定字符串、通配符、glob、逗号或空格分隔的列表、/regex/ 或谓词函数匹配的包名。这也会将它们从 --peer 检查中排除。

--reject 在新版本获取 之前 运行，而 --filterResults 则在 之后 运行。

您还可以在 .ncurc.js 文件中或作为模块导入 npm-check-updates 时指定自定义函数。

⚠️ 谓词函数仅在 .ncurc.js 中或作为模块导入 npm-check-updates 时可用，在命令行上不可用。要将 JSON 配置转换为 JS 配置，请按照 Config Functions 中的说明操作。

/**
  @param name     The name of the dependency.
  @param semver   A parsed Semver array of the current version.
    (See: https://git.coolaj86.com/coolaj86/semver-utils.js#semverutils-parse-semverstring)
  @returns        True if the package should be excluded, false if it should be included.
*/
reject: (name, semver) => {
  if (name.startsWith('@myorg/')) {
    return true
  }
  return false
}

rejectVersion

用法：

ncu --rejectVersion [p]

--filterVersion 的反向操作。排除匹配给定字符串、通配符、glob、逗号或空格分隔的列表，或 /regex/ 的版本。

--rejectVersion 在新版本获取之前运行，而 --filterResults 则在获取之后运行。

若要使用谓词函数进行拒绝，请改用 reject。它会接收包名和解析后的当前版本，因此可以同时对名称和版本进行匹配。

target

用法：

ncu --target [value]
ncu -t [value]

确定要升级到的版本。(默认值: "latest")

greatest	升级到已发布的最高版本号，无论发布日期或标签如何。包括预发布版本。
latest	升级到包 "latest" dist-tag 所指向的版本。与 --cooldown 一起使用时，如果 latest 版本过于近期，则回退到通过冷却阈值检查的最高版本。如需严格行为（跳过该包），请使用 --target "@latest"。除非指定了 --pre，否则不包括预发布版本。
minor	升级到最高的次要版本，而不提升主版本号。
newest	升级到发布日期最近的版本，即使存在更高的版本号。包括预发布版本。
patch	升级到最高的补丁版本，而不提升次要版本或主版本号。
semver	升级到 package.json 中指定的 semver 范围内的最高版本。
@[tag]	升级到发布到特定标签的版本，例如 'next' 或 'beta'。

e.g.

ncu --target semver

你也可以在 .ncurc.js 文件中指定一个自定义函数，或者在将 npm-check-updates 作为模块导入时指定。

⚠️ 谓词函数仅在 .ncurc.js 中或作为模块导入 npm-check-updates 时可用，在命令行上不可用。要将 JSON 配置转换为 JS 配置，请按照 Config Functions 中的说明操作。

/** Upgrade major version zero to the next minor version, and everything else to latest.
  @param name     The name of the dependency.
  @param semver   A parsed Semver object of the upgraded version.
    (See: https://git.coolaj86.com/coolaj86/semver-utils.js#semverutils-parse-semverstring)
  @returns        One of the valid target values (specified in the table above).
*/
target: (name, semver) => {
  if (parseInt(semver[0]?.major) === '0') return 'minor'
  return 'latest'
}

配置文件

在项目目录中添加一个 .ncurc 或 .ncurc.{json,yaml,yml,js,mjs,cjs} 文件以指定配置信息。

无扩展名的 .ncurc 可以是 JSON 或 YAML 格式。例如：

.ncurc:

upgrade: true
filter: svelte
reject:
  - '@types/estree'
  - ts-node

.ncurc.json:

{
  "upgrade": true,
  "filter": "svelte",
  "reject": ["@types/estree", "ts-node"]
}

选项按以下优先级合并：

1. 命令行选项
2. 本地配置文件（当前工作目录）
3. 项目配置文件（位于 package.json 旁边）
4. 用户配置文件（$HOME）

你也可以使用 --configFileName 或 --configFilePath 命令行选项来指定自定义的配置文件名称或路径。

配置函数

某些选项支持通过函数定义进行更高级的配置。这些选项包括 filter、filterVersion、filterResults、reject、rejectVersion 和 groupFunction。要定义这些选项，请使用基于 JavaScript 的配置文件。

ESM（推荐）

将你的配置文件重命名为 .ncurc.js（如果使用 "type": "module"）或 .ncurc.mjs。

import { defineConfig } from 'npm-check-updates'

export default defineConfig({
  upgrade: true,
  filter: name => name.startsWith('@myorg/'),
})

CommonJS

使用 .ncurc.cjs 扩展名或标准的 .ncurc.js 文件（如果使用 "type": "commonjs"）。

const { defineConfig } = require('npm-check-updates')

module.exports = defineConfig({
  upgrade: true,
  filter: name => name.startsWith('@myorg/'),
})

或者，如果您不想使用辅助函数，可以使用 JSDoc 来实现 IntelliSense：

ESM (JSDoc)

/** @type {import('npm-check-updates').RcOptions} */
export default {
  upgrade: true,
  filter: name => name.startsWith('@myorg/'),
}

CommonJS（JSDoc）

/** @type {import('npm-check-updates').RcOptions} */
module.exports = {
  upgrade: true,
  filter: name => name.startsWith('@myorg/'),
}

JSON Schema

如果你使用 json 或 yaml 编写 .ncurc 配置文件，可以将 JSON Schema 添加到你的 IDE 设置中以启用自动补全。

例如，对于 VS Code：

{
  "json.schemas": [
    {
      "fileMatch": [".ncurc", ".ncurc.json"],
      "url": "https://raw.githubusercontent.com/raineorshine/npm-check-updates/main/src/types/RunOptions.json",
    },
  ],
  "yaml.schemas": {
    "https://raw.githubusercontent.com/raineorshine/npm-check-updates/main/src/types/RunOptions.json": [".ncurc.yml"],
  },
}

模块/编程式用法

npm-check-updates 可以作为模块在 ESM 和 CommonJS 环境中导入。

ESM（推荐）

在 package.json 或 .mjs 文件中使用 "type": "module" 的现代项目中，请使用此方式。

import ncu from 'npm-check-updates'

const upgraded = await ncu({
  // Pass any cli option
  packageFile: '../package.json',
  upgrade: true,
  // Defaults:
  // jsonUpgraded: true,
  // silent: true,
})

console.log(upgraded) // { "mypackage": "^2.0.0", ... }

CommonJS

将此用于使用 "type": "commonjs" 的遗留项目或使用 .cjs 扩展名的脚本。

const { default: ncu } = require('npm-check-updates')

// ncu() is an async function
ncu({
  packageFile: './package.json',
  upgrade: true,
}).then(upgraded => {
  console.log(upgraded)
})

贡献

欢迎贡献。我会回复所有 PR，并可以就修改位置提供指导。有关贡献建议，请参阅 CONTRIBUTING.md。

遇到问题？

提交 issue。请先 搜索现有 issue。

许可证

Apache-2.0