快速开始

BundleWatch 需要 Node.js 22.17 或更高版本。从 0.x 升级请参阅迁移到 1.0。想让 AI 编程助手完成设置，请复制这段提示词。

安装

将 BundleWatch 安装为开发依赖：

npmpnpmYarnBun

bash

npm install bundlewatch --save-dev

bash

pnpm add bundlewatch --save-dev

bash

yarn add bundlewatch --dev

bash

bun add bundlewatch --dev

配置

在项目根目录创建 bundlewatch.config.mjs，告诉 BundleWatch 要检查哪些文件，以及它们最大允许多大：

/** @type {import('bundlewatch').BundlewatchConfig} */
export default {
  files: [
    {
      path: './dist/*.js',
      maxSize: '100kB',
    },
  ],
}

构建项目后运行：

bash

npx bundlewatch

BundleWatch 会自动找到 bundlewatch.config.mjs。使用自定义文件名或位置时，可以通过 --config <路径> 指定；参见配置查找。

在你自己的机器上第一次运行时，输出类似这样：

text

[WARNING] Some CI configuration options were not found (githubAccessToken, repoOwner, repoName, commitSha):
    bundlewatch will be unable to report build status, or save comparison data
    Learn more at: https://bundlewatch.io/

Result breakdown at: https://service.bundlewatch.io/results?d=...

PASS ./dist/app.js: 30.71KB < 100KB (gzip)

bundlewatch PASS
Everything is in check (+30.71KB, -0B)

在本机上出现这条警告是正常的：在 CI 中，你会提供 token，而在支持的 CI 服务上，BundleWatch 会自动检测其他值。当某个文件超过其 maxSize，或某个路径没有匹配到任何文件时，命令以退出码 1 退出。

要选定限制，先在不加 maxSize 的情况下运行 npx bundlewatch。没有 maxSize 的文件不受限制，会显示为 PASS ./dist/app.js: 30.71KB < Infinity (gzip)。然后把每个 maxSize 设得比当前体积稍大一些，这样检查既能发现真正的增长，又不会因为每个小改动而失败。

如果你的文件名包含内容 hash，例如 main.3f2a1b9c.js，请设置 normalizeFilenames。否则每次构建的文件看起来都是新文件，没有可以对比的对象。

其他配置方式请参阅使用配置文件，所有选项请参阅配置参考。

在 CI 中运行

在 CI 中于构建之后运行 BundleWatch，它就会在每个 Pull Request 上发布状态，并将每个文件与基准分支对比：

在 GitHub Actions 上，将这个工作流复制到 .github/workflows/bundlewatch.yml。它使用 GitHub 为每次运行创建的 token，你无需自己创建。
在其他 CI 服务上，创建一个 token，将它保存为 secret BUNDLEWATCH_GITHUB_TOKEN，并在构建之后运行 npx bundlewatch。

在推送到某个跟踪分支（例如 main）保存基准之前，Pull Request 没有可以对比的对象。在那之前，日志会显示 Unable to fetch fileDetails … code=404。

使用 AI 编程助手设置

将下面的提示词复制到你的 AI 编程助手中。它会阅读本文档、测量你的构建产物、选定体积限制，并添加 CI 配置：

text

在这个仓库中设置 BundleWatch（https://bundlewatch.io），让 CI 在构建出的文件过大时失败，并让 Pull Request 显示每个文件的体积变化。

先阅读 https://bundlewatch.io/llms-full.txt：其中包含完整的文档。如果这个仓库已经在使用 BundleWatch 0.x，请改为按照 https://bundlewatch.io/guide/migrating-to-v1.md 操作。然后：

1. 找到生产构建命令并运行它。列出它输出的 JavaScript 和 CSS 文件，以及它们的 gzip 体积。
2. 使用这个项目已在使用的包管理器，将 bundlewatch 添加为开发依赖。
3. 在项目根目录创建 bundlewatch.config.mjs，默认导出一个配置对象，每个输出文件对应一个 "files" 条目。使用只匹配文件、不匹配目录，并且在不同构建之间文件名变化时仍能匹配的 glob，并将每个文件的 "maxSize" 设为比当前 gzip 体积高约 10%，向上取整到整数 kB。如果文件名包含内容 hash，请设置 "normalizeFilenames"，使同一个文件在不同构建中保持相同的名称。用实际的文件名检验该模式：它只能移除 hash，并且不能有两个文件最终得到相同的名称。
4. 构建，运行 `npx bundlewatch`，并确保每个文件都通过检查。
5. 在 CI 中于构建之后运行它：
   - 在 GitHub Actions 上，添加 https://bundlewatch.io/guide/using-bundlewatch#github-actions 中的工作流，并根据这个项目的 Node.js 版本、包管理器、构建命令和默认分支进行调整。它不需要任何 secret。
   - 在其他 CI 服务上，添加一个在构建之后运行 `npx bundlewatch` 的步骤，并让我在 https://service.bundlewatch.io/setup-github 创建一个 token，将它保存为 BUNDLEWATCH_GITHUB_TOKEN secret。绝不要提交 token。
6. 总结你修改了什么、你选择的体积限制，以及还剩下哪些需要我来做的事，例如将 `bundlewatch` 设为必需的状态检查。

完整的英文文档也以纯文本形式提供给 AI 编程助手和大语言模型：llms.txt 列出了所有页面，llms-full.txt 包含了全部页面。在英文文档任意页面的 URL 后加上 .md，也可以获取该页面的 Markdown 版本。

下一步

GitHub 状态：在文件过大时阻止合并。
基准分支与跟踪分支：每次构建与什么对比。
配置参考：所有选项和环境变量。
故障排查：每条日志消息的含义。

快速开始 ​

安装 ​

配置 ​

在 CI 中运行 ​

使用 AI 编程助手设置 ​

下一步 ​

快速开始

安装

配置

在 CI 中运行

使用 AI 编程助手设置

下一步