@adobe/sizewatcher 中文文档教程

Question

• How it works
• Requirements
• Installation
• Usage
• CI Setup
• Configuration
• Comparators reference
• Contribute
• Licensing

sizewatcher

sizewatcher 是一个 CI 工具，可以自动警告 Github 拉取请求中的大小增加。 这允许及早检测常见的不良问题，例如

• addition of large dependencies (and transient dependency trees)
• accidental addition of large binary files to the git repository
• sudden increase in build artifact size

虽然可以通过配置测量任何自定义文件或文件夹路径，但会自动测量各种类型，包括 git 存储库、Node 模块依赖性和 npm 包大小 - 请参阅 比较器参考。 更多内置语言 & 选项会随着时间的推移而添加，欢迎贡献。

sizewatcher 作为 CI 的一部分运行，并将结果报告为对拉取请求的评论或作为 github 提交状态（可选），允许在超过特定阈值时阻止 PR。

这是一个失败的 sizewatcher Github PR 评论示例（忽略小数字）：

---

❌ Sizewatcher detected a problematic size increase ????:

❌ git +97.9% (186 kB => 368 kB)

Largest files in new changes:

ecaf42b1d55c  4.5KiB lib/report.js
9c1a82fa7efb  2.8KiB lib/render.js
710a7c687b06  2.8KiB lib/render.js
e7a5a58b23a6  2.7KiB test/config.test.js
0a8f1a2ddb4f  2.4KiB test/config.test.js
6846cf298cd4  2.3KiB test/config.test.js
461b7663fd23  1.6KiB lib/config.js
a643d322cc26  1.5KiB lib/config.js
6db7d5c27a66     69B .sizewatcher.yml

✅ node_modules -6.1% (42.5 MB => 39.9 MB)

Largest node modules:

┌───────────────┬─────────────┬────────┐
│ name          │ children    │ size   │
├───────────────┼─────────────┼────────┤
│ @octokit/rest │ 33          │ 11.25M │
├───────────────┼─────────────┼────────┤
│ js-yaml       │ 3           │ 0.72M  │
├───────────────┼─────────────┼────────┤
│ simple-git    │ 2           │ 0.24M  │
├───────────────┼─────────────┼────────┤
│ tmp           │ 13          │ 0.22M  │
├───────────────┼─────────────┼────────┤
│ debug         │ 1           │ 0.08M  │
├───────────────┼─────────────┼────────┤
│ deepmerge     │ 0           │ 0.03M  │
├───────────────┼─────────────┼────────┤
│ require-dir   │ 0           │ 0.02M  │
├───────────────┼─────────────┼────────┤
│ du            │ 1           │ 0.01M  │
├───────────────┼─────────────┼────────┤
│ pretty-bytes  │ 0           │ 0.01M  │
├───────────────┼─────────────┼────────┤
│ 9 modules     │ 34 children │ 4.57M  │
└───────────────┴─────────────┴────────┘

Notes

- PR branch: `testconfig` @ 21b66dfe6c3f6d09d4929ea2dec1e62cd1a7e7f2 - Base branch: `main` - Sizewatcher v1.0.0 - Effective Configuration:

limits:
  fail: 100%
  warn: 30%
  ok: '-10%'
report:
  githubComment: true
  githubStatus: false
comparators:
  git:
    limits:
      fail: 50%
  custom: null

---

如果一切看起来不错的话：

---

✅ Sizewatcher found no problematic size increases.

✅ git +97.9% (186 kB => 368 kB)

Largest files in new changes:

ecaf42b1d55c  4.5KiB lib/report.js
9c1a82fa7efb  2.8KiB lib/render.js
710a7c687b06  2.8KiB lib/render.js
e7a5a58b23a6  2.7KiB test/config.test.js
0a8f1a2ddb4f  2.4KiB test/config.test.js
6846cf298cd4  2.3KiB test/config.test.js
461b7663fd23  1.6KiB lib/config.js
a643d322cc26  1.5KiB lib/config.js
6db7d5c27a66     69B .sizewatcher.yml

✅ node_modules -6.1% (42.5 MB => 39.9 MB)

Largest node modules:

┌───────────────┬─────────────┬────────┐
│ name          │ children    │ size   │
├───────────────┼─────────────┼────────┤
│ @octokit/rest │ 33          │ 11.25M │
├───────────────┼─────────────┼────────┤
│ js-yaml       │ 3           │ 0.72M  │
├───────────────┼─────────────┼────────┤
│ simple-git    │ 2           │ 0.24M  │
├───────────────┼─────────────┼────────┤
│ tmp           │ 13          │ 0.22M  │
├───────────────┼─────────────┼────────┤
│ debug         │ 1           │ 0.08M  │
├───────────────┼─────────────┼────────┤
│ deepmerge     │ 0           │ 0.03M  │
├───────────────┼─────────────┼────────┤
│ require-dir   │ 0           │ 0.02M  │
├───────────────┼─────────────┼────────┤
│ du            │ 1           │ 0.01M  │
├───────────────┼─────────────┼────────┤
│ pretty-bytes  │ 0           │ 0.01M  │
├───────────────┼─────────────┼────────┤
│ 9 modules     │ 34 children │ 4.57M  │
└───────────────┴─────────────┴────────┘

Notes

- PR branch: `testconfig` @ 21b66dfe6c3f6d09d4929ea2dec1e62cd1a7e7f2 - Base branch: `main` - Sizewatcher v1.0.0 - Effective Configuration:

limits:
  fail: 100%
  warn: 200%
  ok: '-10%'
report:
  githubComment: true
  githubStatus: false
comparators: {}

---

How it works

默认情况下，sizewatcher 将

• checkout the before and after branch versions in temporary directories
• go through all comparators that apply
• measure the sizes, compare and report
• fail ❌ at a 100%+ increase
• warn ⚠️ at a 30%+ increase
• report ok ✅ if the size change is between -10 and +30%
• cheer if there is a 10% decrease
• print result in cli output
• report result as PR comment
• not set a commit status
• as this will block the PR if it fails
• opt-in using report.githubStatus: true, see Configuration below

Requirements

• Nodejs version 10+
• recommended to use latest stable version "LTS"
• Github or Github Enterprise
• if you want to run it on pull requests
• CI system running on Github pull requests
• Github Actions (simplest setup)
• Travis CI
• CircleCI
• others might work too

Installation

在本地安装 sizewatcher 工具，以便在提交之前测试或检查您的更改：

npm install -g @adobe/sizewatcher

Usage

在本地运行时，sizewatcher 将输出其结果在命令行上。

请参阅命令行帮助：

sizewatcher -h

帮助输出：

Usage: sizewatcher [<options>] [<before> [<after>]]

Arguments:
  <before>   Before branch/commit for comparison. Defaults to default branch or main/master.
  <after>    After branch/commit for comparison. Defaults to current branch.

Options:
  -h     Show help

在最简单的情况下，在不带参数的 git 存储库中运行。 这会将当前签出的分支与基础分支（main 或 master）进行比较：

sizewatcher

示例输出：

> sizewatcher
Cloning git repository...
Comparing changes from 'main' to 'docs'

Calculating size changes for
- git
- node_modules

Sizewatcher measured the following changes:

  'main' => 'docs' (sha 15626a050330492da8b745dadb4f5d304b670e83)

+ ✅ git: 0.2% (179 kB => 179 kB)

  Largest files in new changes:

  360cccafa87c    974B .npmignore
...
Error: Cannot identify github repository. Cannot comment on PR or update status checks in github.
Done. Cleaning up...

请注意消息 Error: Cannot identify github repository. 在本地运行就正常了。

将当前分支与不同的基本分支 (base) 进行比较：

sizewatcher base

将任意分支或修订版 before 与 after 进行比较：

sizewatcher before after

CI Setup

• CI Overview
• Github Actions
• Travis CI
• CircleCI
• Other CIs

CI Overview

Run using npx

运行 CI 中的 sizewatcher，它需要自动运行以检查拉取请求，最好使用 npx，它预装了nodejs，会一次性自动下载并运行最新版本：

npx @adobe/sizewatcher

该命令将始终使用最新发布的版本。 在某些情况下，可能（暂时）希望坚持某个版本，这可以通过以下方式实现：

npx @adobe/sizewatcher@1.0.0

GITHUB_TOKEN

为了能够自动评论 PR 或报告提交状态，github 令牌 必须是设置为环境变量：

GITHUB_TOKEN=....

此令牌应该是对存储库具有读取/拉取权限（允许评论）的服务/机器人用户。 请注意，评论将显示在该用户的姓名下。 例如，您可能想要创建一个名为 sizewatcher-bot 或类似名称的用户。 使用 Github Actions 这不是必需的，它有一个内置的 github-actions 机器人用户。

GITHUBAPIURL

如果您使用 Github Enterprise，请在GITHUB_API_URL 环境变量：

GITHUB_API_URL=https://mygithub.company.com/api/v3/

公共 github.com 不需要此变量。

Order of steps

您可以在主要构建步骤之前、之后或同时运行 sizewatcher。 它不依赖于构建的输出，因为它将分别检查代码（PR 版本之前和之后）并且需要自己运行任何构建步骤，例如在 script ="#custom">自定义比较器。

请参阅下面的 CI 特定设置。

Github Actions

对于 Github Actions，您需要

• ensure Node.js is installed using actions/setup-node
• run npx @adobe/sizewatcher
• set a GITHUB_TOKEN which can leverage the built-in secrets.GITHUB_TOKEN (no need to create the token yourself!)

示例 workflow yaml 片段 (.github/workflows/*.yml):

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
    - uses: actions/checkout@v2
    - name: Install Node.js
      uses: actions/setup-node@v1
      with:
        node-version: '14'
    # ---------- this runs sizewatcher ------------
    - run: npx @adobe/sizewatcher
      env:
        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Travis CI

For Travis CI 你需要

• use language: node_js
• if you already use a different language, find a way to ensure Nodejs 10+ is installed
• under script run npx @adobe/sizewatcher
• set a secret environment variable GITHUB_TOKEN in the Travis repository settings with a github token with permission to comment on PRs and reporting commit statuses for the repository

示例 .travis.yml:

language: node_js

install:
  - npm install

script:
  # ---------- this runs sizewatcher ------------
  - npx @adobe/sizewatcher

CircleCI

For CircleCI< /a> 你需要

• use a docker image with Nodejs 10+ installed
• alternatively install using nvm
• run npx @adobe/sizewatcher
• set a secret environment variable GITHUB_TOKEN in the CircleCI project settings (or in a Context) with a github token with permission to comment on PRs and reporting commit statuses for the repository

示例 .circleci/config.yml：

version: 2

jobs:
  build:
    docker:
      - image: circleci/node:14
    steps:
      - checkout

      # ---------- this runs sizewatcher ------------
      - run: npx @adobe/sizewatcher

Other CIs

这没有经过很好的测试，但可能有效。

确保安装了 Nodejs 10+。

在 CI 作业中设置这些环境变量：

• GITHUB_BASE_REF name of the base branch into which the pull request is being merged
• GITHUB_HEAD_REF name of the branch of the pull request
• GITHUB_TOKEN a github token with permission to comment on PRs and reporting commit statuses for the repository. This is a credential so use the proper CI credential management and never check this into the git repository!

然后

npx @adobe/sizewatcher

Configuration

通过在 git 存储库的根目录中创建一个 .sizewatcher.yml 来运行配置 sizewatcher 的行为。 配置文件完全是可选的。

完整示例和参考：

report:
  # to report a github commit status (will block PR if it fails)
  # default: false
  githubStatus: true
  # to report a comment on the github PR
  # default: true
  githubComment: false

# global thresholds when to warn or fail a build
# note that one failing or warning comparator is enough to fail or warn
# can be either
# - percentage: "50%" ("-10%" for size decrease)
# - absolute limit, as byte string: "10 MB", "5 KB"
#   see https://www.npmjs.com/package/xbytes
# - absolute limit, as byte number: 1000000
limits:
  # when to fail - default: 100%
  fail: 50%
  # when to warn - default: 30%
  warn: 10%
  # below the ok limit you will get a cheers for making it notably smaller
  # default: -10%
  ok: -5%

# configure individual comparators
# see list below for available comparators - use exact names as yaml keys
# by default all comparators run if they detect their content is present
comparators:
  # set a comparator "false" to disable it
  git: false

  # customize comparator
  node_modules:
    # specific limits
    # same options as for the "limits" at the root
    limits:
      fail: 10 MB
      warn: 9 MB
      ok: 1 MB

  npm_package:
    # `dir` is supported for all comparators that support it and
    # specifies the relative directory inside the project inside which to run the comparator
    dir: "sub/folder"
    # can also be an array with multiple directories to check
    dir:
      - "sub/folder1"
      - "folder2"

  # custom comparator (only active if configured)
  custom:
    - name: my artifact
      # path to file or folder whose size should be measured
      # path must be relative to repo root
      # comparator only runs if that path exists
      path: build/artifact

    # there can be multiple custom comparators
    # name defaults to the path
    # path can include glob patterns
    - path: "artifact-*.tgz"
      # run some custom build command before measuring
      script: npm install
      # limits can be configured as well
      limits:
        fail: 10 MB

Comparators reference

• git
• node_modules
• npm_package
• custom

git

通过测量 .git 文件夹来比较 git 存储库的大小。 用于检测是否将大文件添加到存储库中。

名称：git

触发器：如果找到 .git 目录，则运行。

Details: Shows the largest files added in the PR:

---

Largest files in new changes:

710a7c687b06  2.8KiB lib/render.js
0a8f1a2ddb4f  2.4KiB test/config.test.js
6846cf298cd4  2.3KiB test/config.test.js
a643d322cc26  1.5KiB lib/config.js
933e4432aae5     73B .sizewatcher.yml
6db7d5c27a66     69B .sizewatcher.yml

---

node_modules

通过测量 node_modules 文件夹的大小来比较 Node.js 依赖项的大小增加。 有助于防止添加不必要的大型依赖项并减慢 npm 安装时间。

名称：node_modules

触发器：如果找到 package.json 则运行。

详细信息：使用 cost-of-modules 打印最大的模块：

---

最大的节点模块：

┌───────────────┬─────────────┬────────┐
│ name          │ children    │ size   │
├───────────────┼─────────────┼────────┤
│ @octokit/rest │ 33          │ 11.25M │
├───────────────┼─────────────┼────────┤
│ js-yaml       │ 3           │ 0.72M  │
├───────────────┼─────────────┼────────┤
│ simple-git    │ 2           │ 0.24M  │
├───────────────┼─────────────┼────────┤
│ tmp           │ 13          │ 0.22M  │
├───────────────┼─────────────┼────────┤
│ debug         │ 1           │ 0.08M  │
├───────────────┼─────────────┼────────┤
│ deepmerge     │ 0           │ 0.03M  │
├───────────────┼─────────────┼────────┤
│ require-dir   │ 0           │ 0.02M  │
├───────────────┼─────────────┼────────┤
│ du            │ 1           │ 0.01M  │
├───────────────┼─────────────┼────────┤
│ pretty-bytes  │ 0           │ 0.01M  │
├───────────────┼─────────────┼────────┤
│ 9 modules     │ 34 children │ 4.57M  │
└───────────────┴─────────────┴────────┘

配置：支持 dir

---

npm_package

通过运行 npm publish --dry-run 比较 npm 包 tarball 的大小。

名称：npm_package

触发器：如果找到 package.json 则运行。

详细信息：使用 npm publish --dry-run 的输出打印包内容和元数据。

---

包内容：

 @adobe/sizewatcher@1.0.0
=== Tarball Contents ===
11.3kB LICENSE
4.8kB  lib/checkout.js
5.2kB  lib/compare.js
1.7kB  lib/config.js
3.9kB  lib/comparators/custom.js
2.3kB  lib/comparators/git.js
2.6kB  lib/github.js
2.1kB  index.js
2.2kB  lib/comparators/node_modules.js
3.9kB  lib/render.js
4.6kB  lib/report.js
1.1kB  package.json
695B   CHANGELOG.md
23.9kB README.md
=== Tarball Details ===
name:          @adobe/sizewatcher
version:       1.0.0
package size:  18.6 kB
unpacked size: 70.3 kB
shasum:        80846caccca2194f3dd1122e8113206e20c202dc
integrity:     sha512-c3VjMQQvqcqN8[...]ybMS6kg2chjpA==
total files:   14

配置：支持 dir

---

custom

比较自定义文件或文件夹的大小。

名称：custom

触发器：如果在之前或之后的版本中找到路径，则运行。

详细信息：显示新文件/文件夹的大小。

---

新尺寸：

18.6 kB README.md

---

配置：

此比较器需要在 .sizewatcher.yml 中配置：

comparators:
  custom:
    path: src/somefile

如果首先需要构建步骤，请使用 script：

comparators:
  custom:
    path: "build/artifact-*.tgz"
    script: npm run build

要有多个路径，使用自定义名称：

comparators:
  custom:
    - name: my artifact 1
      path: "build/artifact"
    - name: my artifact 2
      path: "build/artifact2"

选项：

• path (required) relative path to file or folder to measure; supports glob patterns. make sure to use quotes in the yaml if you use glob patterns
• name (optional) custom label
• script (optional) shell command to run before measuring path
• limits can be set as usual

Contribute

欢迎投稿！ 阅读贡献指南以获得一般指南。

New comparator

如果你想为语言 X 或依赖管理器 Y 添加一个新的自动比较器，请按照下列步骤操作：

1. search issues for any existing similar comparators being discussed
2. if not, create a new issue
3. fork this repo
4. under lib/comparators add your new comparator, say superduper.js
5. must export an object with these functions:

   module.exports = {

       shouldRun: async function(beforeDir, afterDir) {
           // return true if it should run, otherwise false to skip
           // use to automatically detect language, package manager etc.
           return true;
       },

       compare: async function(before, after) {
           // measure differences between before (base branch) and after (pull request)
           // before and after are objects with
           // - `dir`: directory
           // - `branch`: name of the branch
           // - `sha`: (only on "after") commit sha of the PR currently being looked at

           // return an object with
           // - `beforeSize`: size of the before state
           // - `afterSize`: size of the after state
           // - `detailsLabel`: custom label for the details section (shown in expanded section on PR comment)
           // - `details`: text with custom details on the after state (largest files etc)
           return {
               beforeSize: 100
               afterSize: 200
               detailsLabel: "Largest files in new changes",
               details: "... details"
           }
       }
   }

6. test and validate
7. create PR

Licensing

这个项目是在 Apache V2 许可证下获得许可的。 有关详细信息，请参阅许可证。