博客

Oxfmt 实战教程：让你的代码格式化快到飞起

学习使用 Oxfmt，一个比 Prettier 快 10 倍以上的代码格式化工具，从安装配置到编辑器集成，一站式教程。

LibDoc Team 2026年3月4日 OXC 专栏 40 分钟阅读
#oxc #oxfmt #prettier #代码格式化 #rust

Oxfmt 实战教程：让你的代码格式化快到飞起

你是否遇到过这样的场景：运行 prettier --write "./src/**/*" 后，看着文件列表慢慢滚动，几百个文件的格式化需要十几秒甚至更久？

今天，我们要介绍的 Oxfmt 能够彻底改变这种体验。作为 OXC 工具链的格式化工具，它不仅速度快，而且与 Prettier 高度兼容。

代码格式化是什么？

在深入 Oxfmt 之前，先来理解”代码格式化”的意义。

为什么需要格式化代码？

看下面这段代码：

// 格式混乱的代码
const user={name:"张三",age:25,email:"test@example.com"};
function getUserInfo(  user  ){
const{name,age}=user;
return  `用户${name}，年龄${age}`;
}

格式化后：

// 格式整齐的代码
const user = { name: "张三", age: 25, email: "test@example.com" };

function getUserInfo(user) {
  const { name, age } = user;
  return `用户${name}，年龄${age}`;
}

代码格式化的好处：

  • 提高可读性：整齐的代码更容易阅读和理解
  • 减少冲突：统一的风格减少代码审查时的争论
  • 提升效率：自动格式化省去手动调整的时间

Prettier 的普及度

Prettier 是目前最流行的代码格式化工具，几乎所有前端项目都在使用。它的特点：

  • 约定优于配置：提供合理的默认格式
  • 支持多种语言：JavaScript、TypeScript、CSS、HTML、JSON 等
  • 生态丰富：与各种编辑器和工具链集成

Oxfmt 的定位

Oxfmt 是 OXC 项目的一部分，用 Rust 编写，目标是成为 Prettier 的高性能替代品：

  • 速度优势：比 Prettier 快 10-30 倍
  • 高度兼容：支持 Prettier 配置格式
  • 持续进化：功能覆盖度不断提升

安装 Oxfmt

方式一：全局安装

# 使用 npm
npm install -g oxfmt

# 使用 yarn
yarn global add oxfmt

# 使用 pnpm
pnpm add -g oxfmt

方式二：项目内安装

npm install oxfmt --save-dev

在 package.json 中添加脚本：

{
  "scripts": {
    "format": "oxfmt \"./src/**/*.{js,jsx,ts,tsx}\" --write",
    "format:check": "oxfmt \"./src/**/*.{js,jsx,ts,tsx}\" --check"
  }
}

方式三：使用 npx

npx oxfmt "./src/**/*.{js,ts}" --write

快速上手

基本命令

# 格式化单个文件
oxfmt src/main.js --write

# 格式化多个文件（使用 glob 模式）
oxfmt "./src/**/*.{js,jsx,ts,tsx}" --write

# 检查格式是否符合规范（不修改文件）
oxfmt "./src/**/*.{js,ts}" --check

# 显示格式化差异
oxfmt "./src/**/*.js" --diff

命令行选项

选项说明
--write直接修改文件
--check只检查，不修改，返回退出码
--diff显示格式化前后的差异
--config <path>指定配置文件路径

实战：格式化你的第一个项目

让我们完整演练一遍。

步骤一：创建测试文件

创建 src/example.js：

// 故意写得格式混乱
const config={
    debug: true,
  api:"https://api.example.com",
        timeout:5000
}

function   fetchData(  endpoint  ){
const url = config.api+endpoint
    return fetch(url,{timeout:config.timeout})
.then(response=>response.json())
  .catch(error=>{
    console.error('Error:',error)
throw error
  })
}

export{config,fetchData}

步骤二：运行格式化

oxfmt src/example.js --write

步骤三：查看格式化结果

格式化后的代码：

// 格式整齐
const config = {
  debug: true,
  api: "https://api.example.com",
  timeout: 5000,
};

function fetchData(endpoint) {
  const url = config.api + endpoint;
  return fetch(url, { timeout: config.timeout })
    .then((response) => response.json())
    .catch((error) => {
      console.error("Error:", error);
      throw error;
    });
}

export { config, fetchData };

步骤四：使用 —diff 查看差异

oxfmt src/example.js --diff

输出示例：

--- src/example.js
+++ src/example.js (formatted)
@@ -1,13 +1,15 @@
-const config={
-    debug: true,
-  api:"https://api.example.com",
-        timeout:5000
+const config = {
+  debug: true,
+  api: "https://api.example.com",
+  timeout: 5000,
 }

配置文件

Oxfmt 支持通过配置文件自定义格式化规则。

创建配置文件

在项目根目录创建 .oxfmtrc 或 oxfmt.config.js：

// .oxfmtrc
{
  "semi": true,
  "singleQuote": false,
  "tabWidth": 2,
  "useTabs": false,
  "trailingComma": "es5",
  "printWidth": 80,
  "bracketSpacing": true,
  "arrowParens": "always"
}

配置选项详解

选项类型默认值说明
semibooleantrue是否在语句末尾添加分号
singleQuotebooleanfalse使用单引号还是双引号
tabWidthnumber2缩进空格数
useTabsbooleanfalse使用 tab 还是空格缩进
trailingCommastring"es5"尾随逗号规则
printWidthnumber80每行最大字符数
bracketSpacingbooleantrue对象字面量花括号内空格
arrowParensstring"always"箭头函数参数括号

trailingComma 选项

// "none" - 不使用尾随逗号
const obj = {
  a: 1,
  b: 2
};

// "es5" - 在 ES5 支持的地方使用（对象、数组）
const obj = {
  a: 1,
  b: 2,
};

// "all" - 所有地方都使用（包括函数参数）
function example(
  a,
  b,
) {}

arrowParens 选项

// "always" - 总是使用括号
const fn = (x) => x * 2;

// "avoid" - 单参数时省略括号
const fn = x => x * 2;

编辑器集成

在编辑器中自动格式化，能极大提升开发效率。

VS Code 配置

方法一：使用 Oxc 插件

  1. 安装 “Oxc - Oxidation Compiler” 插件
  2. 在 .vscode/settings.json 中配置：
{
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "oxc.oxc-vscode",
  "[javascript]": {
    "editor.defaultFormatter": "oxc.oxc-vscode"
  },
  "[typescript]": {
    "editor.defaultFormatter": "oxc.oxc-vscode"
  }
}

方法二：使用命令行 + 保存时运行

在 .vscode/settings.json 中：

{
  "editor.formatOnSave": true,
  "editor.codeActionsOnSave": {
    "source.fixAll.format": true
  }
}

在 package.json 中添加：

{
  "scripts": {
    "format": "oxfmt \"./src/**/*.{js,ts,jsx,tsx}\" --write"
  }
}

WebStorm / IntelliJ IDEA

  1. 打开 Settings → Tools → External Tools
  2. 添加新工具：
    • Name: Oxfmt
    • Program: npx
    • Arguments: oxfmt "$FilePath$" --write
  3. 设置快捷键或文件保存时自动运行

与 Prettier 的兼容性

Oxfmt 的目标是与 Prettier 高度兼容，但目前仍有部分功能在开发中。

已支持的功能

功能状态
JavaScript/TypeScript 格式化✅ 支持
JSX/TSX 格式化✅ 支持
JSON 格式化✅ 支持
基础配置选项✅ 支持
.prettierrc 配置读取✅ 支持

开发中的功能

功能状态
CSS/SCSS 格式化🚧 开发中
HTML 格式化🚧 开发中
Markdown 格式化🚧 开发中
插件系统🚧 规划中

迁移建议

如果你正在使用 Prettier，可以这样迁移：

  1. 保留 Prettier 配置文件

Oxfmt 可以直接读取 .prettierrc 或 prettier.config.js：

// prettier.config.js
module.exports = {
  semi: true,
  singleQuote: true,
  tabWidth: 2,
  trailingComma: 'es5',
  printWidth: 100,
};
  1. 渐进式替换
{
  "scripts": {
    "format": "oxfmt \"./src/**/*.{js,ts}\" --write",
    "format:prettier": "prettier --write \"./src/**/*.{css,html,md}\""
  }
}

用 Oxfmt 处理 JS/TS，用 Prettier 处理其他文件类型。

性能对比

让我们看看 Oxfmt 和 Prettier 的性能差异。

测试环境

  • 文件数量：200 个 TypeScript 文件
  • 总代码量：约 50,000 行
  • 机器：MacBook Pro M1

测试结果

工具首次运行时间二次运行时间
Prettier3.2 秒2.8 秒
Oxfmt0.15 秒0.12 秒

Oxfmt 比 Prettier 快约 20 倍！

实际影响

在大型项目或 CI/CD 环境中，这个差异更加明显：

场景PrettierOxfmt
pre-commit 钩子10-30 秒0.5-2 秒
CI 格式检查1-2 分钟3-5 秒
全项目格式化数分钟数秒

实用技巧

忽略特定文件

创建 .oxfmtignore 文件：

# .oxfmtignore
node_modules/
dist/
build/
*.min.js
*.d.ts
coverage/

格式化特定范围

使用 glob 模式精确控制：

# 只格式化 src 目录下的组件文件
oxfmt "./src/components/**/*.{jsx,tsx}" --write

# 排除测试文件
oxfmt "./src/**/*.ts" --ignore "./src/**/*.test.ts" --write

与 lint-staged 配合

在 package.json 中：

{
  "lint-staged": {
    "*.{js,jsx,ts,tsx}": [
      "oxfmt --write"
    ]
  }
}

配合 husky 实现 pre-commit 自动格式化：

{
  "scripts": {
    "prepare": "husky install"
  }
}

常见问题

Oxfmt 和 Prettier 的输出不一样？

由于实现差异，某些边缘情况的输出可能不完全一致。可以通过调整配置来减少差异。

如何处理 Prettier 不支持的文件？

保持 Prettier 作为后备：

{
  "scripts": {
    "format": "oxfmt \"./src/**/*.{js,ts,jsx,tsx,json}\" --write && prettier --write \"./src/**/*.{css,scss,html,md}\""
  }
}

Oxfmt 支持哪些语言？

目前支持：

  • JavaScript (.js, .mjs, .cjs)
  • TypeScript (.ts, .tsx, .mts, .cts)
  • JSX (.jsx)
  • JSON (.json)

总结

本文介绍了 Oxfmt 的核心用法：

内容命令
格式化文件oxfmt ./src --write
检查格式oxfmt ./src --check
查看差异oxfmt ./src --diff
配置文件.oxfmtrc 或 oxfmt.config.js

Oxfmt 的核心价值：让代码格式化从”等待”变成”瞬间完成”。

下一步

想了解更多 Oxfmt 的配置选项？访问 OXC 中文文档 - Formatter 章节

下一篇文章，我们将深入 OXC Parser —— 探索代码解析的魔法，理解 AST 是如何工作的！

💡 相关阅读：