配置

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 字段以获得编辑器验证和自动补全：

.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 令牌

要匹配 Prettier 的默认值：

.oxfmtrc.json

{
  "printWidth": 80
}

oxfmt.config.ts

import { defineConfig } from "oxfmt";

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

后续步骤

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