第 3 章 · format 命令实战

3.1 命令基础

# 检查但不改（默认模式）
biome format ./src
→ 退出码 0 = 无差异; 非 0 = 有文件需要格式化

# 写入磁盘
biome format --write ./src

# 指定扩展名范围
biome format --write "src/**/*.{ts,tsx,js,jsx}"

# 只处理 staged 的改动
biome format --staged --write

3.2 核心风格参数

indentStyle / indentWidth: 缩进。"tab"（默认）或 "space"。Prettier 默认 2 空格；Biome 默认 tab 体现其"无障碍友好"立场。
lineWidth: 软行宽，默认 80，建议设 100–120。Biome 会尽量把表达式压到这个宽度内。
lineEnding: "lf" | "crlf" | "cr"。团队应显式写 lf，避免 Windows 提交 crlf。
javascript.formatter.quoteStyle: 字符串引号，"single" 或 "double"（默认）。
javascript.formatter.jsxQuoteStyle: JSX 属性引号，独立于 JS。React 惯例 "double"。
javascript.formatter.semicolons: "always"（默认）或 "asNeeded"（只在必要时）。选 asNeeded = 你选了 no-semi 风格。
javascript.formatter.trailingCommas: "all"（ES2017+，默认）、"es5"、"none"。all 让 git diff 更干净。
javascript.formatter.arrowParentheses: "always"（(x) => x）或 "asNeeded"（x => x）。always 有利于后续加类型。
javascript.formatter.bracketSpacing: 对象字面量是否加空格：{ a: 1 } vs {a: 1}。默认 true。
javascript.formatter.bracketSameLine: JSX 开闭标签的 > 是否单独成行。
javascript.formatter.attributePosition: "auto" 或 "multiline"。multiline 让 JSX 属性逐行排列，diff 更易读。

3.3 常用配置组合

标准 React/Next 风格

"javascript": {
  "formatter": {
    "quoteStyle": "double",
    "jsxQuoteStyle": "double",
    "semicolons": "always",
    "trailingCommas": "all",
    "arrowParentheses": "always",
    "lineWidth": 100
  }
}

Airbnb/Node 风格（单引号、no-semi）

"javascript": {
  "formatter": {
    "quoteStyle": "single",
    "semicolons": "asNeeded",
    "trailingCommas": "all"
  }
}

3.4 Biome 与 Prettier 的已知差异

Biome 官宣 Prettier 兼容度 97%，剩下 3% 是刻意选择。常见差异：

场景	Prettier	Biome
默认缩进	2 空格	tab
三元表达式换行	启发式断行	更一致的规则
JSX 属性换行阈值	略激进	略保守
对象解构保留尾逗号	是	是
单行 import 不会被强拆多行	是	是

差异完整对照表见 https://biomejs.dev/formatter/#differences-with-prettier。团队切换 Biome 时建议先跑一次 biome format --write，把"一次性重排 diff"单独作为一次提交，后续 code review 就不会再有噪声。

3.5 stdin 模式

给编辑器/脚本用——从标准输入读代码、格式化后输出到标准输出：

echo "const x=1" | biome format --stdin-file-path=foo.ts
→ const x = 1;

必须带 --stdin-file-path，Biome 据此判断语言（ts/tsx/jsx/json/css）。

3.6 禁用格式化：魔法注释

有些场景（对齐表格、ASCII 图、生成的代码）不希望被格式化：

// biome-ignore format: keep this aligned
const matrix = [
  [1, 0, 0],
  [0, 1, 0],
  [0, 0, 1],
];

注释后面紧跟"下一个语句"会被整体跳过格式化。

3.7 多语言：JSON / CSS / GraphQL

biome format --write "**/*.{json,jsonc}"
biome format --write "**/*.css"
biome format --write "**/*.graphql"

CSS 格式化在 Biome v2 稳定，规则接近 stylelint 的默认 pretty 输出。

Markdown / YAML 呢？

Biome 目前不支持 Markdown 与 YAML 的格式化（在路线图上）。如果需要，可叠加 dprint 或 Prettier 专门处理这两类。

3.8 性能对比实测

# 一个 20 万行的真实 Next.js 项目（仅 format）
prettier .  # ~18.2s
biome format .  # ~0.52s
# 约 35× 加速

小结

biome format 的 10 来个参数决定了"你的代码长什么样"。先按团队风格在 biome.json 里定一次、用一次 --write 作为"格式化大爆炸"提交，之后就靠 IDE 保存时格式化 + pre-commit 把风格自动稳定下来。下一章转到 lint 规则。