Wireit 升级您的 npm 脚本，使其更智能、更高效。

特性

• 🙂 使用你已知的 npm run 命令
• ⛓️ 自动并行运行 npm 脚本之间的依赖
• 👀 监视任意脚本并在更改时持续重新运行
• 🥬 跳过已经是最新状态的脚本
• ♻️ 在本地和 GitHub Actions 上免费缓存输出
• 🛠️ 适用于单包、npm workspaces 以及其他 monorepos
• ✏️ VSCode 插件 在开发过程中提供建议、文档和警告

目录

• 特性
• 安装
• 设置
• VSCode 扩展
• Discord
• 依赖项
  • 原生脚本
  • 跨包依赖
• 并行性
• 额外参数
• 输入和输出文件
  • 示例配置
  • 默认排除的路径
• 增量构建
• 缓存
  • 本地缓存
  • GitHub Actions 缓存
• 清理输出
• 监视模式
• 服务
• 执行级联
• 环境变量
• 故障和错误
• 包锁定
• 配方
  • TypeScript
  • ESLint
• 参考
  • 配置
  • 依赖语法
  • 环境变量参考
  • Glob 模式
  • 指纹
• 要求
• 相关工具
• 贡献

安装

npm i -D wireit

设置

Wireit 与 npm run 配合使用，而不是替代它。要为 Wireit 配置 NPM 脚本，请将命令移动到 package.json 中的新 wireit 部分， 并用 wireit 命令替换原始脚本。

{
  "scripts": {
    "build": "tsc"
  }
}

{
  "scripts": {
    "build": "wireit"
  },
  "wireit": {
    "build": {
      "command": "tsc"
    }
  }
}

现在，当你运行 npm run build 时，Wireit 会将脚本升级为更智能、 更高效。Wireit 也适用于 node --run、yarn 和 pnpm。

你还应该在 .gitignore 文件中添加 .wireit。Wireit 使用 .wireit 目录来存储脚本的缓存和其他数据。

echo .wireit >> .gitignore

VSCode 扩展

如果你使用 VSCode，请考虑安装 google.wireit 扩展。它提供悬停文档、自动补全功能，能够诊断多种常见错误，甚至建议重构以将 npm 脚本转换为使用 wireit。

从 marketplace 或通过命令行安装，例如：

code --install-extension google.wireit

Discord

加入 Wireit Discord 与 Wireit 社区交流，并为你的项目获取支持。

依赖项

要声明两个脚本之间的依赖关系，请编辑 wireit.<script>.dependencies 列表：

{
  "scripts": {
    "build": "wireit",
    "bundle": "wireit"
  },
  "wireit": {
    "build": {
      "command": "tsc"
    },
    "bundle": {
      "command": "rollup -c",
      "dependencies": ["build"]
    }
  }
}

现在当你运行 npm run bundle 时，build 脚本会自动先运行。

原生脚本

你依赖的脚本无需为 Wireit 进行配置，它们可以是 原生的 npm 脚本。这让你可以仅对部分脚本使用 Wireit， 或进行渐进式升级。未配置 Wireit 的脚本 始终可以安全地用作依赖项；只是它们不会得到完全优化。

仅限 Wireit 的脚本

在 wireit 部分中定义一个不在 scripts 部分中的脚本是有效的，但此类脚本只能作为其他 wireit 脚本的 dependencies 使用， 且永远无法直接运行。

跨包依赖

依赖项可以通过使用相对路径和语法 <relative-path>:<script-name> 来引用其他 npm 包中的脚本。所有跨包依赖 都应以 "." 开头。跨包依赖在 npm 工作区以及其他类型的 monorepo 中都能很好地工作。

{
  "scripts": {
    "build": "wireit"
  },
  "wireit": {
    "build": {
      "command": "tsc",
      "dependencies": ["../other-package:build"]
    }
  }
}

并行性

Wireit 会在依赖图允许的情况下尽可能并行运行脚本。

例如，在下图中，B 和 C 脚本将并行运行， 而 A 脚本在 B 和 C 都完成之前不会启动。

graph TD
  A-->B;
  A-->C;
  subgraph parallel
    B;
    C;
  end

默认情况下，Wireit 会为系统上检测到的每个逻辑 CPU 核心并行运行最多 2 个脚本。要更改此默认值，请将 WIREIT_PARALLEL 环境变量 设置为正整数，或 infinity 以无限制地运行。如果在大型构建中遇到资源不足的情况，您可能希望降低此数值。例如，要一次只运行一个 脚本：

export WIREIT_PARALLEL=1
npm run build

如果同时运行两个或更多针对同一 Wireit 脚本的独立 npm run 命令，则一次只允许一个实例运行，其余实例将等待轮次。这可以防止可能导致生成不正确输出文件的协调问题。如果将 output 设置为空数组，则此限制将被移除。

额外参数

与普通的 npm 脚本一样，你可以通过在 Wireit 脚本前放置一个 -- 双破折号参数来传递额外参数。-- 之后的任何参数都会发送给底层命令，而不是被解释为 npm 或 Wireit 的参数：

npm run build -- --verbose

或者更一般地：

npm run {script} {npm args} {wireit args} -- {script args}

使用 node --run 时，需要额外的 -- 以区分 分别用于 node、wireit 以及脚本本身的参数：

node --run {script} {node args} -- {wireit args} -- {script args}

输入和输出文件

wireit.<script> 的 files 和 output 属性分别告诉 Wireit 你的脚本的输入文件和输出文件是什么。它们应该是 glob 模式] 的数组，其中路径是相对于包目录解释的。它们可以设置在你的部分、全部或没有脚本上。

设置这些属性允许你使用 Wireit 的更多功能：

示例配置

{
  "scripts": {
    "build": "wireit",
    "bundle": "wireit"
  },
  "wireit": {
    "build": {
      "command": "tsc",
      "files": ["src/**/*.ts", "tsconfig.json"],
      "output": ["lib/**"]
    },
    "bundle": {
      "command": "rollup -c",
      "dependencies": ["build"],
      "files": ["rollup.config.json"],
      "output": ["dist/bundle.js"]
    }
  }
}

默认排除的路径

默认情况下，以下文件夹被排除在 files 和 output 数组之外：

• .git/
• .hg/
• .svn/
• .wireit/
• .yarn/
• CVS/
• node_modules/

在极不寻常的情况下，如果你需要引用这些文件夹中的某个文件，请设置 allowUsuallyExcludedPaths: true 以移除所有默认排除项。

增量构建

如果自上次运行以来，没有任何会导致输出发生变化的更改，Wireit 可以自动跳过脚本的执行。这被称为 增量构建。

要为每个脚本启用增量构建，请在 wireit.<script>.files 和 wireit.<script>.output 数组中指定 glob 模式 来配置输入和输出文件。

ℹ️ 如果脚本根本没有定义 files 或 output 列表，那么它将 始终 运行，因为 Wireit 不知道要检查哪些文件是否发生了变化。若要告诉 Wireit 可以安全地跳过执行某个确定没有输入和/或文件的脚本，请将 files 和/或 output 设置为空数组（files: [], output: []）。

缓存

如果脚本之前使用相同的配置和输入文件成功运行过，那么 Wireit 可以从缓存中复制输出，而不是运行命令。这可以显著改善构建和测试时间。

要为脚本启用缓存，请确保你已同时定义了 files 和 output 数组。

ℹ️ 如果脚本不产生任何输出文件，仍可通过将 output 设置为空数组（"output": []）来对其进行缓存。空输出在测试中很常见，并且很有用，因为它允许你在测试之前使用完全相同的输入通过时跳过运行测试。

本地缓存

在 本地 模式下，Wireit 将 output 文件缓存到每个包内的 .wireit 文件夹中。

本地缓存默认启用，除非检测到 CI=true 环境变量。要强制启用本地缓存，请设置 WIREIT_CACHE=local。要禁用本地缓存，请设置 WIREIT_CACHE=none。

⚠️ Wireit 目前不限制本地缓存的大小。要释放此 空间，请使用 rm -rf .wireit/*/cache。自动缓存大小限制将在 即将发布的版本中添加，跟踪于 wireit#71。

GitHub Actions 缓存

在 GitHub Actions 模式下，Wireit 将 output 文件缓存到 GitHub Actions cache 服务。此服务在 GitHub Actions 中运行时始终可用，并且 对所有 GitHub 用户免费。

ℹ️ GitHub Actions 缓存条目会在 7 天后自动删除，或者如果 总使用量超过 10 GB（最近最少使用的缓存条目会先被 删除）。有关更多详细信息，请参阅 GitHub Actions documentation。

要在 GitHub Actions 上启用缓存，请将以下 uses 子句添加到您的工作流中。它可以出现在第一个 npm run 或 npm test 命令之前的任何位置：

- uses: google/wireit@setup-github-actions-caching/v2

示例工作流

# File: .github/workflows/tests.yml

name: Tests
on: [push, pull_request]
jobs:
  tests:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: actions/setup-node@v6
        with:
          node-version: 24
          cache: npm

      # Set up GitHub Actions caching for Wireit.
      - uses: google/wireit@setup-github-actions-caching/v2

      # Install npm dependencies.
      - run: npm ci

      # Run tests. Wireit will automatically use
      # the GitHub Actions cache whenever possible.
      - run: npm test

清理输出

Wireit 可以在执行脚本之前自动删除上次运行生成的输出文件。这有助于确保每次构建都是干净的，并且不包含由于源文件已被移除而在先前运行中创建的过时文件。

只要定义了 output 数组，清理功能默认启用。要更改此行为， 请将 wireit.<script>.clean 属性设置为以下值之一：

监视模式

在 watch 模式下，Wireit 会监视脚本的所有 files 及其所有传递依赖项的 files，当检测到变更时，仅重新运行受影响的脚本。要启用监视模式，请首先确保已定义 files 数组，然后运行：

WIREIT_WATCH=true npm run <script>

Wireit 的 watch 模式相较于 Node 及其他程序内置的 watch 模式的优势在于：

• Wireit 监控整个依赖图，因此单个 watch 命令可替代 许多内置命令。
• 它防止了在同时运行多个独立的 watch 命令时可能出现的问题， 例如在先前步骤全部完成之前触发了构建步骤。

默认情况下，watch 模式使用操作系统上可用的文件系统变更 API。此行为可通过 WIREIT_WATCH_STRATEGY 和 WIREIT_WATCH_POLL_MS 环境变量进行更改（参见 下文）。

环境变量

使用 env 设置可以直接设置环境变量，或者 指示外部定义的环境变量会影响脚本的行为。

直接设置环境变量

如果 env 对象中的属性值为字符串，则当脚本的 command 运行时， 该环境变量将被设置为该值， 覆盖来自父进程的任何值。

与内置的 shell 环境变量语法不同，使用 env 设置 环境变量在 macOS/Linux 与 Windows 上以及所有 shell 中的行为一致。

注意 使用 env 设置的环境变量不会 通过依赖关系传递。如果需要对多个脚本设置相同的环境变量， 必须为每个脚本分别进行配置。

{
  "wireit": {
    "my-script": {
      "command": "my-command",
      "env": {
        "MY_VARIABLE": "my value"
      }
    }
  }
}

指示外部环境变量

如果某个环境变量会影响脚本的行为，但它是_外部_设置的（即它被传递给 wireit 父进程），请将 env 属性设置为 {"external": true}。这告诉 Wireit，如果某个环境变量的值在脚本的多次执行之间发生变化，则其输出 不应被重新使用。您还可以为该变量设置一个 default 值， 以便在外部未提供该值时使用。

{
  "wireit": {
    "my-script": {
      "command": "my-command",
      "env": {
        "MY_VARIABLE": {
          "external": true
        },
        "MY_VARIABLE_2": {
          "external": true,
          "default": "foo"
        }
      }
    }
  }
}

服务

默认情况下，Wireit 假设你的脚本最终会自行退出。 这非常适合构建和测试脚本，但不适用于服务器等长时间运行的 进程。要告诉 Wireit 某个进程是长时间运行的且 预期不会自行退出，请设置 "service": true。

{
  "scripts": {
    "start": "wireit",
    "build:server": "wireit"
  },
  "wireit": {
    "start": {
      "command": "node my-server.js",
      "service": true,
      "files": ["my-server.js"],
      "dependencies": [
        "build:server",
        {
          "script": "../assets:build",
          "cascade": false
        }
      ]
    },
    "build:server": {
      ...
    }
  }
}

服务生命周期

如果服务被_直接_运行（例如 npm run serve），则它会保持运行状态， 直到用户终止 Wireit（例如 Ctrl-C）。

如果服务是一个或多个其他脚本的_依赖项_，则它会在任何依赖脚本运行之前启动， 并在所有依赖脚本完成后关闭。

服务就绪状态

默认情况下，服务在其进程生成时即被视为_就绪_， 从而允许依赖该服务的任何脚本开始运行。

然而，通常服务需要在依赖项与其交互之前执行某些操作， 例如启动服务器并监听网络接口。

使用 service.readyWhen.lineMatches 告知 Wireit 监控服务的 stdout 和 stderr，并推迟就绪状态，直到打印出匹配给定正则表达式的行。

{
  "command": "node my-server.js",
  "service": {
    "readyWhen": {
      "lineMatches": "Server listening on port \\d+"
    }
  }
}

服务重启

在 watch 模式下，每当服务的任一输入文件或 依赖项发生变化时，该服务都会重启，但 cascade 设置为 false 的依赖项除外。

服务输出

服务不能有 output 文件，因为 Wireit 无法知道 服务何时完成其输出的写入。

如果你有一个产生输出的服务，你应该定义一个 非服务 脚本，该脚本依赖于它，并在服务的输出 完成时退出。

执行级联

默认情况下，如果其任一依赖项需要运行，脚本始终需要运行（或在 services 的情况下重启），无论 该依赖项是否产生了新的或相关的输出。

这种脚本执行的自动 级联 是默认行为，因为它 确保依赖脚本产生的任何 可能的 输出都会传播到所有可能依赖于它的其他 脚本。换句话说，Wireit 并不假设 files 数组完全描述了具有依赖项的脚本的输入。

禁用级联

可以通过将依赖项展开为 对象，并将 cascade 属性设置为 false 来禁用此执行级联行为：

注意 实际上，底层发生的情况是 cascade 属性仅控制 脚本的 fingerprint 是否包含其依赖项的指纹，而这又决定了脚本是否需要运行或重启。

{
  "dependencies": [
    {
      "script": "foo",
      "cascade": false
    }
  ]
}

禁用级联的原因

你可能希望将 cascade 设置为 false 的两个主要原因是：

1. 你的脚本仅消费依赖项输出的子集。

   例如，tsc 同时生成 .js 文件和 .d.ts 文件，但可能只有 .js 文件会被 rollup 消费。当仅发生 typings 变更时，无需重新打包。

   注意 除了将 cascade 设置为 false 之外，确实 重要的输出子集（lib/**/*.js） 已被添加到 files 数组中。

   {
     "scripts": {
       "build": "wireit",
       "bundle": "wireit"
     },
     "wireit": {
       "build": {
         "command": "tsc",
         "files": ["src/**/*.ts", "tsconfig.json"],
         "output": ["lib/**"]
       },
       "bundle": {
         "command": "rollup -c",
         "dependencies": [
           {
             "script": "build",
             "cascade": false
           }
         ],
         "files": ["rollup.config.json", "lib/**/*.js"],
         "output": ["dist/bundle.js"]
       }
     }
   }

2. 您的服务器在某些更改时无需重启。

   例如，Web 服务器依赖于一些静态资源，但服务器会在每次请求时从磁盘动态读取这些资源。在 watch 模式下， 当资源发生变化时，无需重启服务器。

   注意 build:server 依赖项使用默认的 cascade 行为 (true)，因为更改服务器本身的实现 确实 需要重启服务器。

   {
     "scripts": {
       "start": "wireit",
       "build:server": "wireit"
     },
     "wireit": {
       "start": {
         "command": "node lib/server.js",
         "service": true,
         "dependencies": [
           "build:server",
           {
             "script": "../assets:build",
             "cascade": false
           }
         ],
         "files": ["lib/**/*.js"]
       },
       "build:server": {
         "command": "tsc",
         "files": ["src/**/*.ts", "tsconfig.json"],
         "output": ["lib/**"]
       }
     }
   }

故障与错误

默认情况下，当脚本失败（即返回非零退出码）时， 所有正在运行的脚本都被允许继续执行直至完成，但不会启动新的脚本。

在某些情况下，不同的行为可能更为合适。有 2 种额外的模式，您可以通过 WIREIT_FAILURES 环境变量进行设置。请注意，无论处于何种模式， 只要发生故障，Wireit 最终始终以非零退出码退出。

继续

当在 continue 模式下发生故障时，正在运行的脚本将继续执行，并且只要故障未影响其依赖项， 新的脚本仍会被启动。此模式适用于您希望全面了解哪些脚本 成功以及哪些脚本失败的情况。

WIREIT_FAILURES=continue

Kill

当 kill 模式中出现故障时，正在运行的脚本会立即被终止， 且不会启动新的脚本。如果您希望尽快收到任何故障的通知，此模式非常有用。

WIREIT_FAILURES=kill

包锁定文件

默认情况下，Wireit 会自动将包管理器锁定文件视为输入 文件 （npm 为 package-lock.json ，yarn 为 node --run， yarn.lock， pnpm 为 pnpm-lock.yaml）。Wireit 会在脚本所在的包以及所有父 目录中查找这些锁定文件。

这很有用，因为安装或升级依赖项可能会影响 脚本的行为，因此每当依赖项 发生变化时，重新运行它们非常重要。

若要更改 Wireit 应查找的包锁定文件名称，请在 wireit.<script>.packageLocks 数组中指定。如有需要， 您可以在此指定多个文件名。

{
  "scripts": {
    "build": "wireit"
  },
  "wireit": {
    "build": {
      "command": "tsc",
      "files": ["src/**/*.ts", "tsconfig.json"],
      "output": ["lib/**"],
      "packageLocks": ["another-package-manager.lock"]
    }
  }
}

如果你确定某个脚本完全不受依赖项的影响，你可以通过将 wireit.<script>.packageLocks 设置为 [] 来完全关闭此行为，以提高缓存命中率。

配方

本节包含有关将特定构建工具与 Wireit 集成的建议。

TypeScript

{
  "scripts": {
    "ts": "wireit"
  },
  "wireit": {
    "ts": {
      "command": "tsc --build --pretty",
      "clean": "if-file-deleted",
      "files": ["src/**/*.ts", "tsconfig.json"],
      "output": ["lib/**", ".tsbuildinfo"]
    }
  }
}

• 设置 "incremental": true 并使用 --build 以启用增量编译，这将显著提升性能。
• 在 output 中包含 .tsbuildinfo，以便在清理构建时重置。否则 tsc 会失去 同步并产生错误的输出。
• 设置 "clean": "if-file-deleted"，以便在源文件更改/添加时获得快速 的增量编译，同时在源文件被删除时清理过时的输出 （tsc 本身不会清理过时的输出）。
• 在 files 中包含 tsconfig.json，以便更改配置时重新运行 tsc。
• 使用 --pretty 以在 未连接到 TTY 的情况下获得彩色输出。

ESLint

{
  "scripts": {
    "lint": "wireit"
  },
  "wireit": {
    "lint": {
      "command": "eslint --color --cache --cache-location .eslintcache .",
      "files": ["src/**/*.ts", ".eslintignore", ".eslintrc.cjs"],
      "output": []
    }
  }
}

• 使用 --cache 以便 eslint 仅检查自上次运行以来新增或修改的文件，从而显著提升性能。
• 使用 --color 以在未连接到 TTY 的情况下获取彩色输出。
• 在 files 中包含配置和忽略文件，以便更改配置时重新运行 eslint。

参考

配置

以下属性可以在 package.json 文件中的 wireit.<script> 对象内设置：

依赖语法

以下语法可用于 wireit.<script>.dependencies 数组：

环境变量引用

以下环境变量会影响 Wireit 的行为：

Glob 模式

files 和 output 数组中支持以下 glob 语法：

另请注意以下细节：

• 路径应始终使用 /（正斜杠）作为分隔符，即使在 Windows 上也是如此。
• 即使路径以 / 开头，路径也是相对于当前包进行解释的 （例如 /foo 等同于 foo）。
• 每当匹配到一个目录时，该目录的所有递归子项都会被 包含在内。
• files 允许使用例如 ../foo 来访问当前包之外的内容。output 文件不能引用当前 包之外的文件。
• 输入 files 中的符号链接会被跟随，以便通过其内容进行识别。
• output 文件中的符号链接会被缓存为符号链接，以便从 缓存恢复时不会创建不必要的副本。
• !exclude 模式的顺序很重要。
• 隐藏/点文件由 * 和 ** 匹配。
• 模式区分大小写（如果文件系统支持）。

Fingerprint

以下输入决定了脚本的 fingerprint。该值用于 确定是否可以跳过脚本的 增量 构建，以及其输出是否可以 从 缓存恢复。

• command 设置。
• 在命令行上设置的 额外参数。
• clean 设置。
• output 通配符模式。
• 所有匹配 files 的文件的 SHA256 内容哈希。
• 当前包及所有父目录中所有匹配 packageLocks 的文件的 SHA256 内容哈希。
• 在 env 中配置的环境变量值。
• 系统平台（例如 linux、win32）。
• 系统 CPU 架构（例如 x64）。
• 系统 Node 版本（例如 24.11.1）。
• 所有传递依赖项的指纹，除非将 cascade 设置为 false。

使用 GitHub Actions 缓存 时，以下 输入也会影响指纹：

• ImageOS 环境变量（例如 ubuntu20、macos11）。

要求

Wireit 支持 Linux、macOS 和 Windows。

Wireit 支持 Node 18+。

Wireit 脚本可以通过 npm、node --run、pnpm 和 yarn 启动。

相关工具

Wireit 与以下其他优秀工具共享许多功能，我们强烈 建议您也查看它们：

• Nx
• Turborepo
• Chomp
• Bazel

以下是您可能特别喜欢的 Wireit 的一些特点：

• 感觉像 npm。当你使用 Wireit 时，你将继续输入你已经在使用的相同 npm 命令，例如 npm run build 和 npm test。没有 需要学习的新命令行工具，并且运行每个脚本只有一种方式。 你的脚本配置也保留在你的 package.json 中。Wireit 旨在成为 获取脚本依赖项和增量 构建所需的最小 npm 补充。

• 通过 GitHub Actions 进行缓存。Wireit 支持直接通过 GitHub Actions 缓存构建产物和 测试结果，无需任何额外的第三方 服务。只需在你的工作流中添加一行 uses:。

• 监视任何脚本。想要在你每次进行更改时自动重新运行你的构建和测试 吗？输入 npm test --watch。任何你使用 Wireit 配置的脚本都可以通过在其后输入 --watch 来监视。

• 非常适合单包和 monorepo。Wireit 对 你的包如何组织没有意见。它非常适合单包，因为你可以 将同一包内的脚本链接在一起。它也适用于 任何类型的 monorepo，因为你可以使用相对路径将不同 包中的脚本链接在一起。

• 补充 npm workspaces。我们认为 Wireit 可能是那个缺失的工具， 能够释放 npm workspaces 成为设置 monorepo 的最佳方式 的潜力。要将 Wireit 与 npm workspaces 一起使用，你只需 使用标准的 npm workspace 命令，例如 npm run build -ws。

• 逐步采用。Wireit 脚本可以依赖普通的 npm 脚本，因此可以随意混用。这意味着你可以仅在构建中最需要 Wireit 的部分使用它，或者在不进行太多同时更改的情况下，逐个脚本地尝试使用它。

贡献

参见 CONTRIBUTING.md