🥦 Taze

^{(/ta:zei/，fresh 在波斯语中)}

一个保持你的依赖项新鲜的现代 cli 工具

npx taze

或针对 monorepos 递归执行

npx taze -r

或供 agents 消费

npx taze -r --json

Recursive mode

功能

内置支持 monorepos
无需安装 — npx taze
默认安全 — 仅更新您允许的版本范围内的更新
交互模式以选择要更新的包
尊重 package.json 的 engines 字段以及您的包管理器的配置
更新工作流中的 GitHub Actions，支持可选的 SHA 固定
代理兼容的 JSON 输出

用法

默认情况下，taze 仅会提升您在 package.json 中指定的范围内的版本 (这是安全的，也是 npm install 的默认行为)

Default mode

要忽略范围，请显式设置允许的最大版本变更。

例如，taze major 将检查所有变更并升级到最新的稳定版本，包括主版本（破坏性变更），或者 taze minor 将在同一主版本内升级到最新的小版本。

检查 major 更新
Major mode

检查至多 minor 更新
Minor mode

检查至多 patch 更新
Patch mode

Monorepo

taze 具有内置的一等 monorepo 支持。只需添加 -r 即可扫描包含 package.json 的子目录并一起更新它们。它将自动处理本地私有包。

Recursive mode default

配置

更多详情请参见 taze --help

过滤器

您可以通过 --include 或 --exclude 过滤掉您希望检查升级的包；它们接受字符串和正则表达式，以逗号 (,) 分隔。

taze --include lodash,webpack
taze --include /react/ --exclude react-dom # regex is also supported

--exclude（以及 --include）还接受一个 name@range 选择器，用于仅排除某个包的特定版本范围，而不是整个包。这在需要阻止某个特定主版本，同时仍允许其他更新（包括在交互模式下）时非常有用：

# skip typescript's major v7 (and later), but still offer v6 minor/patch updates
taze --exclude typescript@7
taze --exclude "typescript@^7||^8" # multiple ranges can be combined with ||

pnpm 的 update.ignoreDeps 中列出的依赖项在 pnpm-workspace.yaml 中会被自动排除，因此你告知 pnpm 永不更新的包也会被 taze 跳过。

锁定版本

锁定（固定版本，不含 ^ 或 ~）的包默认会被跳过，使用 taze --include-locked 或 taze -l 来显示它们。

对等依赖

在 peerDependencies 中提升版本默认未启用。传入 --peer 选项以将其包含在更新过程中。

taze --peer

成熟期

默认情况下，使用依赖项的最新版本。您可以通过传递 --maturity-period 来筛选已发布时间更长的版本。

taze --maturity-period

使用成熟期标志时，过滤器为 7 天。您可能还想传递一个天数值，以获得更长或更短的天数。

taze --maturity-period 14

您可以从成熟度过滤器中排除软件包。当可用时，这也会从包管理器配置中推断得出，例如 pnpm-workspace.yaml 中的 minimumReleaseAgeExclude 和 .yarnrc.yml 中的 npmPreapprovedPackages。

taze --maturity-period-exclude react,webpack

如果你只想获取稳定版本，同时仍遵守成熟期要求，请使用 stable 模式。

taze stable --maturity-period 14

[!NOTE] 这种过滤方式在其他工具中有时被称为 cooldown 或 minimumReleaseAge。

JSON 输出

传入 --json 可将解析后的更新信息以 JSON 格式输出到 stdout，而不是渲染后的表格。这在脚本编写和 CI 中非常实用。

taze --json

当使用 --json 时，--interactive 将被忽略，并且不会打印进度条、表格或提示。默认情况下，仅包含有可用更新的依赖项；将其与 --all 结合使用，也可包含已是最新版本的依赖项。它仍可与 -w 结合使用，将更改写回 package.json。

GitHub Actions

taze 还会检查您工作流中使用的 GitHub Actions。当存在 .github/workflows 目录时，它会扫描 .github/workflows/*.{yml,yaml}、复合操作（.github/actions/**/action.{yml,yaml} 和仓库根目录下的 action.{yml,yaml}）以及可复用工作流调用，然后报告较新的版本，与您的 npm 依赖项并列显示。它适用于所有模式（major、minor、...）、--interactive、--json 和 -w。

taze major -w      # also updates outdated actions, e.g. actions/checkout@v3 -> @v4
taze --no-github-actions   # opt out

引用会在原地更新，同时保留你编写的粒度（@v4 → @v5，@v4.1.1 → @v4.2.0）。默认情况下，每个操作的现有样式会被保留：标签引用保持为标签，而 SHA 固定的引用保持固定（并带有更新的 # vX.Y.Z 注释）。使用 --github-actions-style <auto|tag|sha> 显式选择样式：

# style: sha — pin to an immutable commit for supply-chain safety
- uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
# style: tag
- uses: actions/checkout@v5

仅考虑 v 前缀的版本标签；分支引用（@main）、非 v 标签、docker:// 以及本地（./）操作均保持不变。过滤（--include/--exclude/packageMode）、成熟期冷却以及模式均适用，并按操作的 owner/repo 名称进行匹配。

版本从 GitHub REST API 获取。设置 GITHUB_TOKEN（或 GH_TOKEN）可将速率限制从每小时 60 次提升至 5000 次：

GITHUB_TOKEN=xxxx taze major

如果两者都未设置，taze 会回退到 GitHub CLI (gh auth token) 的令牌，前提是你已登录，因此已认证的 gh 无需额外配置。

配置文件

通过 taze.config.js 文件，你可以配置与命令相同的选项。

import { defineConfig } from 'taze'

export default defineConfig({
  // ignore packages from bumping
  exclude: [
    'webpack'
  ],
  // fetch latest package info from registry without cache
  force: true,
  // use a custom fast-npm-meta compatible API endpoint
  fastNpmMetaApiEndpoint: 'https://npm.example.com/',
  // retry behavior when fetching package metadata fails:
  // a number for retry count, `false` to disable, or an object for fine-grained
  // control, e.g. { retries: 4, factor: 2, minTimeout: 1000, maxTimeout: 30_000, randomize: false }
  retry: 4,
  // write to package.json
  write: true,
  // run `npm install` or `yarn install` right after bumping
  install: true,
  // ignore paths for looking for package.json in monorepo
  ignorePaths: [
    '**/node_modules/**',
    '**/test/**',
  ],
  // ignore package.json that in other workspaces (with their own .git,pnpm-workspace.yaml,etc.)
  ignoreOtherWorkspaces: true,
  // override with different bumping mode for each package
  packageMode: {
    'typescript': 'major',
    'unocss': 'ignore',
    // regex starts and ends with '/'
    '/vue/': 'latest'
  },
  // exclude packages from the maturity period filter
  maturityPeriodExclude: [
    'react',
    '@myorg/*',
  ],
  // disable checking for "overrides" package.json field
  depFields: {
    overrides: false
  },
  // GitHub Actions updates: `true` (default) | `false` to opt out | options object
  githubActions: {
    // 'auto' (preserve existing style) | 'tag' | 'sha'
    style: 'auto'
  }
})

替代方案

taze 受到以下工具的启发。

它们运行良好，但侧重点和功能集有所不同，也欢迎尝试一下 :)

致谢

非常感谢 @sinoon，他在头脑风暴和反馈讨论中提供了大量帮助。

GitHub Actions 更新功能受 Azat S. 的 actions-up 启发并致谢，该工具开创了本功能所基于的交互式 SHA 固定工作流。