OxcFmt 与 OxcLint 使用指南

发表于 更新于 分类于
从零上手 OxcFmt 与 OxcLint，完成格式化、规则检查、npm scripts 集成，以及提交前钩子（含 Husky 与非 Node 仓库的 core.hooksPath 等写法）。

前言

前端工程里，eslint + prettier 是常见组合，但在大仓库下执行速度和一致性成本一直是团队关注点。
oxc 提供了以性能为导向的工具链，其中 OxcFmt 负责代码格式化，OxcLint 负责规则检查。
从 oxc 官方 benchmark 口径看，Oxlint 相比 ESLint 约快 50x-100x，Oxfmt 相比 Prettier 约快 35x。
它最明显的优势就是速度，在大仓库和高频改动场景下能显著缩短格式化与规则检查的等待时间。
对需要频繁本地校验的团队来说，更快的反馈意味着更短的提交回路和更高的开发效率。
这篇文章聚焦一个可直接落地的最小流程。
你会完成本地安装、命令验证、npm scripts 集成。
你还会把格式化接到 pre-commit 上：Node 项目可用 husky，非 Node 仓库可用 core.hooksPath 等原生机制。

安装

先在项目里安装 OxcFmt 与 OxcLint 命令行工具。
下面命令通过 npm 安装开发依赖，适合大多数 JavaScript/TypeScript 项目。

npm

1
2
npm install -D oxfmt
npm install -D oxlint

如果你希望在本机任意目录直接使用命令，也可以选择全局安装。
下面脚本更适合个人环境快速体验，团队协作场景仍建议优先使用项目本地依赖。

1
2
npm install -g oxfmt
npm install -g oxlint

安装完成后，先确认本地工具可用。
下面命令会输出版本信息，确保命令已正确安装。

1
2
npx oxfmt --version
npx oxlint --version

pnpm

1
2
pnpm install -D oxfmt
pnpm install -D oxlint

如果你希望在本机任意目录直接使用命令，也可以选择全局安装。
下面脚本更适合个人环境快速体验，团队协作场景仍建议优先使用项目本地依赖。

1
2
pnpm install -g oxfmt
pnpm install -g oxlint

安装完成后，先确认本地工具可用。
下面命令会输出版本信息，确保命令已正确安装。

1
2
pnpm oxfmt --version
pnpm oxlint --version

VS Code 配置

如果你希望在 VS Code 里按保存自动格式化，可以把默认格式化器切到 Oxc 扩展。
先在扩展市场安装 Oxc，扩展标识是 oxc.oxc-vscode。

使用Oxc后建议把Prettier - Code formatter卸载，否则两者都占内存，作用都一样。

下面配置会把全局默认格式化器设为 OxcFmt，并在保存时自动执行格式化。

1
2
3
4
5
{
  "editor.defaultFormatter": "oxc.oxc-vscode",
  "editor.formatOnSave": true,
  "editor.formatOnSaveMode": "file"
}

如果你只想让 JavaScript/TypeScript 使用 OxcFmt，建议改为按语言设置，避免影响其他语言。
下面示例只对前端常见四种文件类型生效。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
  "[javascript]": {
    "editor.defaultFormatter": "oxc.oxc-vscode"
  },
  "[typescript]": {
    "editor.defaultFormatter": "oxc.oxc-vscode"
  },
  "[javascriptreact]": {
    "editor.defaultFormatter": "oxc.oxc-vscode"
  },
  "[typescriptreact]": {
    "editor.defaultFormatter": "oxc.oxc-vscode"
  }
}

如果项目里同时安装了 Prettier，请确保它没有被设为同语言的默认格式化器。
推荐职责划分是 OxcFmt 负责格式，OxcLint 负责规则检查。

Scripts

把常用命令统一收敛到 package.json 的 scripts，可以降低团队使用门槛。
下面示例把“检查”和“自动修复”拆成两个清晰入口。

1
2
3
4
5
6
7
8
9
{
  "scripts": {
    "format": "oxfmt . --write",
    "format:check": "oxfmt . --check",
    "lint": "oxlint src",
    "lint:fix": "oxlint . --fix",
    "check": "npm run format:check && npm run lint"
  }
}

如果你的仓库是多包结构，建议把命令中的 . 改成具体目录。
例如 src、packages/*/src 等路径可以减少无关扫描。
另外要注意，Oxfmt 只会格式化它当前支持的语言和文件类型，不会处理所有文件。
如果仓库里同时包含 markdown、yaml、后端代码等内容，建议按目录拆分脚本，避免把不相关文件放进同一次格式化流程。
按 oxc 官方文档，Oxfmt 当前支持的格式可以按类型分组如下。

  • 脚本与类型：javascript、jsx、typescript、tsx
  • 数据与配置：json、jsonc、json5、yaml、toml
  • 样式：css、scss、less
  • 标记与内容：html、markdown、mdx、graphql
  • 模板与框架：angular、vue、ember、handlebars

提交前钩子

要在每次 git commit 之前自动跑格式化，本质是注册 pre-commit 钩子。
下面给出两种常见粒度，按仓库规模二选一即可。

整仓格式化

适合小仓库，或可以接受每次提交前扫描整个目录的场景。
先安装 husky 并初始化，它会生成 .husky 目录与示例钩子。

1
2
npm install -D husky
npx husky init

把 .husky/pre-commit 的内容改成只调用你在上一节定义的格式化脚本。
这样提交前会执行 oxfmt . --write，与本地手动 npm run format 一致。

1
npm run format

若你还希望在提交前顺带跑静态检查，可以在同一文件里追加一行 npm run lint，注意会拉长每次提交耗时。

仅暂存文件

大仓库更推荐 lint-staged，只对本次 git add 过的文件调用 oxfmt，避免整仓扫一遍。

1
npm install -D husky lint-staged

在 package.json 里增加 lint-staged 配置，并按项目实际扩展名调整 glob。
下面示例覆盖常见前端文件类型，若目录与上一节 scripts 不一致，请自行收窄路径。

1
2
3
4
5
{
  "lint-staged": {
    "*.{js,jsx,ts,tsx,mjs,cjs,json,css,scss,md,mdx,vue}": "oxfmt --write"
  }
}

把 .husky/pre-commit 改成调用 lint-staged，由它在提交前逐个处理暂存文件。

1
npx lint-staged

较新的 lint-staged 会把被工具改写的文件重新加入暂存区，因此提交里通常是格式化后的最终内容。

检查与拦截

若你更希望「不自动改文件、只拦错误提交」，可以把钩子里的命令换成 npm run format:check。
此时开发者需要先在本地执行 npm run format 修复格式，否则 commit 会被拒绝。

团队协作

请把 .husky/ 目录与 package.json 里的相关配置一并提交进仓库。
其他成员执行 npm install 后才能在各自环境得到一致的钩子行为。
若不用 husky，也可以手写 .git/hooks/pre-commit。
这类路径默认不会随仓库共享，协作时容易漂移。

非 Node 仓库

不是以 Node 为主栈、或不想为钩子单独引入 npm 依赖时，仍然可以用 Git 自带的 pre-commit。
差别在于脚本放在哪、怎样让同事克隆后自动生效。

下面做法把可执行脚本放进仓库内的 githooks/（目录名可自定），再用 core.hooksPath 告诉 Git 去那里找钩子。
这样钩子文件可以随仓库提交，避免每人手写 .git/hooks 导致不一致。

先在仓库根创建 githooks/pre-commit，内容按你真实的格式化命令改写。
示例仅演示「提交前只做检查、失败则中断提交」；若工具支持写回，也可以改成等价于 oxfmt ... --write 的流程。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
#!/bin/sh
set -e

# 获取暂存区的文件列表
files=$(git diff --cached --name-only --diff-filter=ACM)

# 遍历每一个文件
for file in $files; do
  # 可选：增加文件后缀过滤，避免格式化二进制文件或无关文件
  # 假设 ox 项目通常是 .rs 或 .toml，根据实际情况修改
  case "$file" in
    *.html|*.js|*.css)
      # 格式化文件
      oxfmt "$file"
      # 格式化后，文件工作区变了，需要重新 add 进暂存区，否则提交的是格式化前的代码
      git add "$file"
      ;;
  esac
done

在 macOS 与 Linux 上需要为该脚本加上可执行权限，否则 Git 不会运行它。

1
chmod +x githooks/pre-commit

每名开发者在克隆仓库后执行下面配置一次即可，建议写进 README 以免遗漏。

1
git config core.hooksPath githooks

在 Windows 上若使用 Git 自带的 Bash 环境，上述 sh 脚本通常可直接使用。
若团队统一用 PowerShell，也可以让 pre-commit 成为薄包装，再调用 pwsh -File scripts/hook.ps1 等，按实际约定即可。

在你配置了 git config core.hooksPath githooks 之后，Git 会把 githooks/ 当成钩子目录，里面的 pre-commit 会在「执行一次 git commit、且即将真正生成提交」之前跑一遍。

如果githooks在子目录可以这样写

1
git config core.hooksPath web/githooks

验证

建议按下面顺序做一次端到端验证，确认本地行为稳定可复现。

  1. 新建一个故意格式错误的文件并运行 npm run format:check，确认命令失败。
  2. 运行 npm run format 后再次执行 npm run format:check，确认命令通过。
  3. 新增一个会触发规则告警的片段并运行 npm run lint，确认有清晰报错。
  4. 在可自动修复的场景下运行 npm run lint:fix，再次执行 npm run lint 确认问题消失。
  5. 按上一节为仓库配置 pre-commit（husky、lint-staged 或 githooks/ 与 core.hooksPath 等）后，故意留下格式问题并执行 git commit，确认钩子会改写或拦截提交。

总结

OxcFmt 与 OxcLint 的组合可以覆盖“格式统一 + 规则校验”这条最常见的前端质量链路。
建议把本地默认入口固定为 npm run check，让团队始终使用同一套检查命令。
再配合 pre-commit 把 format 或 format:check 接到提交流程，可以把个人习惯固化成仓库级约束。
非 Node 仓库同样适用这条思路，只是钩子载体从 husky 换成 core.hooksPath 或通用框架即可。
只要入口一致，团队排查问题和迁移旧仓库都会更顺滑。