设置 CI 及其他集成

🌐 Setup CI and other integrations

你可以——而且应该——设置你的 CI 流水线来运行 Oxfmt，并在格式有差异时使构建失败。

🌐 You can - and should - set up your CI pipeline to run Oxfmt and fail the build on formatting differences.

本页面还涵盖了你可能想要包含的其他集成，例如 git 预提交钩子。

🌐 This page also covers other integrations you may want to include, like git pre-commit hooks.

CI

GitHub 操作

🌐 GitHub Actions

首先，如果你的 package.json 中还没有 fmt:check 脚本，先添加一个：

🌐 First, add a fmt:check script to your package.json if you don't have one already:

package.json

{
  "scripts": {
    "fmt:check": "oxfmt --check"
  }
}

然后在你的 GitHub Actions 工作流中添加一个任务：

🌐 And then add a job to your GitHub Actions workflow:

.github/workflows/ci.yml

name: CI

on:
  pull_request:
  push:
    branches: [main]

permissions: {}

jobs:
  format:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6

      - uses: pnpm/action-setup@v4

      - uses: actions/setup-node@v6
        with:
          node-version: lts/*
          cache: pnpm

      # Or yarn, npm, etc.
      - run: pnpm install --frozen-lockfile
      - run: pnpm run fmt:check

自动修复格式问题

🌐 Autofix formatting issues

如果你发现自己经常忘记在打开 PR 之前运行 Oxfmt，并且不能或不使用 pre-commit 钩子，你可以使用 autofix.ci 在 CI 工作流中添加一个自动修复步骤。

🌐 If you find that you often forget to run Oxfmt before opening PRs, and don't or can't use pre-commit hooks, you can add an autofix step to your CI workflow using autofix.ci.

详情请参阅 https://autofix.ci/setup，你还需要安装相应的 GitHub 应用。

🌐 See https://autofix.ci/setup for more details, you will need to install the relevant GitHub App as well.

下面是一个你可以使用的 GitHub Actions 工作流程示例：

🌐 Below is an example GitHub Actions workflow you can use:

.github/workflows/autofix.yml

name: autofix.ci # needs to use this name

on:
  pull_request:
  push:
    branches: ["main"]

permissions:
  contents: read

jobs:
  autofix:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6

      - uses: pnpm/action-setup@v4

      - uses: actions/setup-node@v6
        with:
          node-version: lts/*
          cache: pnpm

      # Or yarn, npm, etc.
      - run: pnpm install --frozen-lockfile

      # Run oxfmt to write changes, autofix.ci will commit them if there are any differences.
      # Be sure to add a `fmt` script to your `package.json` if you haven't already.
      - run: pnpm run fmt

      # NOTE: It is strongly recommended to use the latest SHA hash for this action instead of the version number. (See https://autofix.ci/setup for more details.)
      - uses: autofix-ci/action@1.3.2

GitLab 持续集成

🌐 GitLab CI

如果你使用 GitLab CI，你可以设置 Oxfmt 在你的 CI 流水线中强制执行代码格式化。

🌐 If you use GitLab CI, you can set up Oxfmt to enforce code formatting as part of your CI pipeline.

首先，如果你的 package.json 中还没有 fmt:check 脚本，先添加一个：

🌐 First, add a fmt:check script to your package.json if you don't have one already:

package.json

{
  "scripts": {
    "fmt:check": "oxfmt --check"
  }
}

然后向你的 .gitlab-ci.yml 添加一个任务，以检查所有代码的格式是否正确：

🌐 And then add a job to your .gitlab-ci.yml, to check that all code is formatted correctly:

.gitlab-ci.yml

oxfmt:
  image: node:lts
  stage: test
  before_script:
    # Or pnpm, yarn, etc.
    - npm install
  script:
    - npm run fmt:check

你可能还想为你的包管理器添加缓存以加快安装速度。

🌐 You may also want to add caching for your package manager to speed up installs.

预提交钩子

🌐 Pre-commit hook

要自动格式化已暂存的文件，请使用 oxfmt --no-error-on-unmatched-pattern。这会格式化所有受支持的文件，并在没有匹配文件时避免错误（例如，只暂存了 Ruby 文件时）。

🌐 To auto-format staged files, use oxfmt --no-error-on-unmatched-pattern. This formats all supported files and avoids errors when no files match (e.g., only Ruby files are staged).

使用 --check 来验证格式而无需写入文件。

🌐 Use --check to verify formatting without writing files.

对于 lint-staged，请添加到 package.json：

🌐 For lint-staged, add to package.json:

package.json

{
  "lint-staged": {
    "*": "oxfmt --no-error-on-unmatched-pattern"
  }
}

在安装依赖时自动安装 git 钩子，也可以考虑使用 husky。

🌐 To automatically install the git hook when installing dependencies, considering also using husky.