biome.json 配置全解

2.1 配置文件的三种形态

Biome 支持三种配置文件名，按优先级从高到低为：

1. biome.jsonc — 允许注释与尾逗号（推荐）
2. biome.json — 标准 JSON
3. 命令行 --config-path 显式指定的任意路径

2.2 顶层结构全览

{
  "$schema": "https://biomejs.dev/schemas/2.0.0/schema.json",
  "extends": ["./packages/config/biome.base.json"],

  "files": {
    "include": ["src/**", "scripts/**"],
    "ignore": ["dist/**", "**/*.generated.ts"],
    "ignoreUnknown": true
  },

  "vcs": {
    "enabled": true,
    "clientKind": "git",
    "useIgnoreFile": true
  },

  "formatter": { /* §2.3 */ },
  "linter":    { /* §2.4 */ },
  "organizeImports": { /* §2.5 */ },
  "javascript": { /* §2.6 */ },
  "json": { /* §2.7 */ },
  "css": { /* §2.8 */ },

  "overrides": [ /* §2.9 */ ]
}

$schema

指向当前 Biome 版本的 JSON Schema——VSCode/WebStorm 读到它后会自动提供字段补全与值校验。建议把 schema URL 里的版本号与 @biomejs/biome 的 devDependency 版本保持一致。

files.include / ignore

用 glob 决定哪些文件被处理。注意：

• include 不写默认 = 所有支持的语言
• ignore 应该额外写上生成产物、第三方依赖镜像等
• 开启 vcs.useIgnoreFile: true 可自动继承 .gitignore——大多数项目只需要这个就够

2.3 formatter 模块

"formatter": {
  "enabled": true,
  "formatWithErrors": false,
  "indentStyle": "space",        // "tab" | "space"
  "indentWidth": 2,
  "lineWidth": 100,
  "lineEnding": "lf",
  "attributePosition": "auto",   // JSX 属性换行策略
  "bracketSpacing": true,
  "bracketSameLine": false
}

这是全局默认，各语言小节（javascript.formatter、json.formatter、css.formatter）可覆盖语言专属设置，例如 JSON 不应用 JS 的 semicolons。

2.4 linter 模块

"linter": {
  "enabled": true,
  "rules": {
    "recommended": true,
    "suspicious": {
      "noExplicitAny": "warn"
    },
    "style": {
      "useConst": "error",
      "noParameterAssign": "off"
    },
    "correctness": {
      "noUnusedVariables": "error"
    }
  }
}

规则组织成7 大分组：correctness（正确性）、suspicious（疑似 Bug）、style（风格）、complexity（复杂度）、performance、security、a11y。每条规则取值为 "off" | "warn" | "error"。详见第 4 章。

2.5 organizeImports

"organizeImports": {
  "enabled": true
}

开启后 biome check --write 会把 import 语句按以下顺序重排：Node 内置 → 第三方包 → 绝对路径别名 → 相对路径。同路径源的 named import 字母序、去重。

2.6 javascript 小节

"javascript": {
  "formatter": {
    "quoteStyle": "single",       // 'x' 还是 "x"
    "jsxQuoteStyle": "double",
    "semicolons": "always",         // "always" | "asNeeded"
    "trailingCommas": "all",
    "arrowParentheses": "always"
  },
  "globals": ["Bun", "Deno"]
}

2.7 json 小节

"json": {
  "parser": {
    "allowComments": true,        // 对 jsonc 文件
    "allowTrailingCommas": true
  },
  "formatter": {
    "indentWidth": 2,
    "trailingCommas": "none"
  }
}

2.8 css 小节（Biome v2+）

"css": {
  "parser": { "cssModules": true },
  "formatter": {
    "quoteStyle": "double"
  },
  "linter": { "enabled": true }
}

2.9 overrides：文件级覆盖

当某组文件需要特殊规则，用 overrides 替代"全局改 + 再全局加回来"。

"overrides": [
  {
    "include": ["**/*.test.ts", "**/*.spec.ts"],
    "linter": {
      "rules": {
        "suspicious": { "noExplicitAny": "off" },
        "complexity": { "noExcessiveCognitiveComplexity": "off" }
      }
    }
  },
  {
    "include": ["packages/legacy/**"],
    "linter": { "enabled": false }
  }
]

2.10 extends：继承共享配置

monorepo 常见做法：

// packages/config/biome.base.json — 共享基线
{
  "$schema": "https://biomejs.dev/schemas/2.0.0/schema.json",
  "linter": { "rules": { "recommended": true } }
}

// apps/web/biome.json — 每包按需扩展
{
  "extends": ["../../packages/config/biome.base.json"],
  "linter": {
    "rules": {
      "a11y": { "useKeyWithClickEvents": "error" }
    }
  }
}

小结

一份 biome.json 的关键字段：$schema（IDE 补全）、files（范围）、formatter + linter + organizeImports（三大模块）、javascript/json/css（语言级覆盖）、overrides（文件级覆盖）、extends（继承）。掌握这张结构图，后续章节的所有命令都只是在操纵它。