配置

Oxfmt 无需额外设置即可直接使用，但大多数团队会提交一个配置文件，以确保本地运行、编辑器和 CI 之间格式化保持一致。

本页重点介绍项目级配置：格式化选项、忽略模式以及实验性功能。

创建配置文件

在当前目录生成初始配置文件：

oxfmt --init

Oxfmt 会从当前目录开始，向上遍历目录树，自动查找 .oxfmtrc.json 或 .oxfmtrc.jsonc。你也可以显式指定配置文件：

oxfmt -c path/to/yourconfig.json

一个最小的配置文件如下所示：

.oxfmtrc.json

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

配置文件格式

配置文件是一个 JSON 对象。最常见的顶层字段包括：

• printWidth: 行宽限制（默认值：100）
• tabWidth: 每级缩进的空格数（默认值：2）
• useTabs: 使用制表符而非空格（默认值：false）
• semi: 添加分号（默认值：true）
• singleQuote: 使用单引号（默认值：false）
• trailingComma: 多行结构中的尾随逗号（默认值："all"）
• ignorePatterns: 用于排除格式化的 glob 模式
• sortImports: 配置导入排序（默认禁用）
• sortTailwindcss: 配置 Tailwind CSS 类名排序（默认禁用）
• 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
      }
    }
  ]
}

每个覆盖项包含：

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

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

优先级顺序

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

1. 默认值
2. .oxfmtrc.json(c) 根级选项
3. .oxfmtrc.json(c) overrides 选项
4. 对未设置的字段回退至 .editorconfig 支持的选项

Oxfmt 特有选项

insertFinalNewline

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

这是 Prettier 中经常被请求的功能，因为某些环境（如 Salesforce）会删除尾部换行符。

printWidth

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

• 由于类型注解，TypeScript 代码通常更长
• 导入语句往往包含多个说明符
• 现代屏幕更宽
• 更少的换行意味着更少的 LLM token

若要与 Prettier 的默认值保持一致：

.oxfmtrc.json

{
  "printWidth": 80
}

下一步

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