配置

Oxfmt 开箱即用，但大多数团队会提交一个配置文件，以保持本地运行、编辑器和 CI 之间的格式化一致。

本页面专注于项目配置：格式化选项、忽略模式和实验性功能。

创建配置文件

在当前目录生成一个初始配置：

oxfmt --init

Oxfmt 会从被格式化文件所在的目录开始向上查找以下文件：

• .oxfmtrc.json
• .oxfmtrc.jsonc
• oxfmt.config.ts

距离每个被格式化文件最近的配置文件优先。这意味着您可以在项目树的不同层级放置不同的配置文件。 例如，整个仓库的根配置，以及子目录中更具体的配置：

my-repo/
├── oxfmt.config.ts         # 整个仓库的默认配置
├── src/
│   └── app.ts              # 使用根配置
└── packages/
    └── fancy-app/
        ├── .oxfmtrc.json   # 该包的覆盖配置
        └── index.ts        # 使用 packages/fancy-app/.oxfmtrc.json

如果您不需要嵌套配置，可以传递 --disable-nested-config 仅从当前工作目录向上查找。这会更快，因为 Oxfmt 可以只解析一次配置而不是每个文件都解析。

您也可以通过 -c 显式传递配置，这也会禁用嵌套配置查找。这接受任何支持的格式（.json、.jsonc、.ts、.mts、.cts、.js、.mjs、.cjs）：

oxfmt -c path/to/yourconfig.json

一个最简 JSON 配置如下：

.oxfmtrc.json

{
  "$schema": "./node_modules/oxfmt/configuration_schema.json",
  "printWidth": 80
}

JavaScript / TypeScript 配置文件使用默认导出。defineConfig 是可选的，但可以提供类型检查和编辑器自动补全：

oxfmt.config.ts

import { defineConfig } from "oxfmt";

export default defineConfig({
  printWidth: 80,
});

配置文件格式

配置文件是一个 JSON 对象。最常见的顶级字段有：

• printWidth：行宽限制（默认：100）
• tabWidth：缩进空格数（默认：2）
• useTabs：使用制表符代替空格（默认：false）
• semi：添加分号（默认：true）
• singleQuote：使用单引号（默认：false）
• trailingComma：多行结构中的尾随逗号（默认："all"）
• ignorePatterns：排除格式化的 glob 模式
• sortImports：配置导入排序（默认禁用）
• sortTailwindcss：配置 Tailwind 类名排序（默认禁用）
• sortPackageJson：配置 package.json 排序（默认启用）

完整字段列表请参阅 配置文件参考。

JSON schema

添加 $schema 字段以获得编辑器验证和自动补全：

.oxfmtrc.json

{
  "$schema": "./node_modules/oxfmt/configuration_schema.json"
}

.editorconfig

Oxfmt 会读取这些 .editorconfig 属性：

• end_of_line → endOfLine
• indent_style → useTabs
• indent_size → tabWidth
• max_line_length → printWidth
• insert_final_newline → insertFinalNewline

支持根部分和基于 glob 的覆盖。

[*]
indent_size = 4

[*.{js,ts}]
indent_size = 2

Oxfmt 仅使用当前目录最近的 .editorconfig：

• 不支持 root = true
• 不合并嵌套的 .editorconfig 文件

覆盖配置

使用 overrides 字段为特定文件应用不同的格式化选项：

.oxfmtrc.json

{
  "printWidth": 100,
  "overrides": [
    {
      "files": ["*.test.js", "*.spec.ts"],
      "options": {
        "printWidth": 120
      }
    },
    {
      "files": ["*.md", "*.html"],
      "excludeFiles": ["*.min.js"],
      "options": {
        "tabWidth": 4
      }
    }
  ]
}

oxfmt.config.ts

import { defineConfig } from "oxfmt";

export default defineConfig({
  printWidth: 100,
  overrides: [
    {
      files: ["*.test.js", "*.spec.ts"],
      options: {
        printWidth: 120,
      },
    },
    {
      files: ["*.md", "*.html"],
      excludeFiles: ["*.min.js"],
      options: {
        tabWidth: 4,
      },
    },
  ],
});

每个覆盖条目包含：

• files（必需）：匹配文件的 glob 模式
• excludeFiles（可选）：从该覆盖中排除的 glob 模式
• options：要应用的格式化选项

Glob 模式相对于包含 Oxfmt 配置文件的目录解析。

优先级

选项按以下顺序应用（从低到高优先级）：

1. 默认值
2. 配置文件根选项
3. 配置文件 overrides 选项
4. 对于未设置的字段，回退到 .editorconfig 支持的选项

Oxfmt 特有选项

insertFinalNewline

控制是否在格式化文件末尾添加换行符。默认为 true。

这是一个常被请求的 Prettier 功能，因为某些环境（如 Salesforce）会去除尾随换行符。

printWidth

Oxfmt 默认 printWidth: 100（Prettier 使用 80）。原因：

• TypeScript 代码因类型注解而更长
• 导入语句通常有许多说明符
• 现代屏幕更宽
• 更少的换行意味着更少的 LLM token

要匹配 Prettier 的默认值：

.oxfmtrc.json

{
  "printWidth": 80
}

oxfmt.config.ts

import { defineConfig } from "oxfmt";

export default defineConfig({
  printWidth: 80,
});

下一步

• 忽略文件：忽略文件和模式，.gitignore 和 .prettierignore 工作流程。
• 内联忽略注释：针对特定代码的内联抑制。
• 配置文件参考：完整 schema 和字段文档。
• CLI 参考：完整标志列表。