⚡

Biome代码格式化Skill biome-formatting

Biome代码格式化技能用于配置和使用Biome快速格式化工具，对JavaScript、TypeScript、JSON等前端代码进行格式化，确保代码风格一致性和团队协作效率。关键词：Biome、代码格式化、前端开发、配置管理、风格指南、JavaScript、TypeScript。

前端开发 0 次安装 0 次浏览 更新于 3/25/2026

name: biome-formatting user-invocable: false description: 使用Biome快速格式化JavaScript/TypeScript代码时使用，包括模式、选项和代码样式管理。 allowed-tools: [Read, Write, Edit, Bash, Glob, Grep]

Biome 格式化

掌握 Biome 的快速代码格式化工具，用于 JavaScript、TypeScript、JSON 和其他支持的语言，确保一致的风格执行。

概述

Biome 的格式化器提供类似于 Prettier 的意见化、快速代码格式化，但性能更好。它是用 Rust 编写的，旨在在团队间一致地格式化代码。

核心命令

基本格式化

# 格式化文件并写入更改
biome format --write .

# 格式化特定文件
biome format --write src/**/*.ts

# 检查格式化而不修复
biome format .

# 格式化标准输入
echo "const x={a:1}" | biome format --stdin-file-path="example.js"

组合操作

# 一起进行代码检查和格式化
biome check --write .

# 仅格式化（跳过代码检查）
biome format --write .

# CI 模式（检查代码检查和格式化）
biome ci .

格式化器配置

全局设置

{
  "formatter": {
    "enabled": true,
    "formatWithErrors": false,
    "indentStyle": "space",
    "indentWidth": 2,
    "lineEnding": "lf",
    "lineWidth": 80,
    "attributePosition": "auto"
  }
}

选项：

  • enabled：启用/禁用格式化器（默认：true）
  • formatWithErrors：即使有语法错误也格式化（默认：false）
  • indentStyle：“space” 或 “tab”（默认：“tab”）
  • indentWidth：空格数，通常为 2 或 4（默认：2）
  • lineEnding：“lf”、“crlf” 或 “cr”（默认：“lf”）
  • lineWidth：最大行长度（默认：80）
  • attributePosition：HTML/JSX 的 “auto” 或 “multiline”

推荐配置

{
  "formatter": {
    "enabled": true,
    "indentStyle": "space",
    "indentWidth": 2,
    "lineEnding": "lf",
    "lineWidth": 100
  }
}

语言特定格式化

JavaScript/TypeScript

{
  "javascript": {
    "formatter": {
      "enabled": true,
      "quoteStyle": "single",
      "jsxQuoteStyle": "double",
      "quoteProperties": "asNeeded",
      "trailingCommas": "all",
      "semicolons": "always",
      "arrowParentheses": "always",
      "bracketSpacing": true,
      "bracketSameLine": false,
      "attributePosition": "auto"
    }
  }
}

引号样式

{
  "javascript": {
    "formatter": {
      "quoteStyle": "single",      // 'string' vs "string"
      "jsxQuoteStyle": "double"     // <div attr="value">
    }
  }
}

示例：

// quoteStyle: "single"
const message = 'Hello, world!';
const name = 'Alice';

// quoteStyle: "double"
const message = "Hello, world!";
const name = "Alice";

// jsxQuoteStyle: "double"
<button onClick={handleClick} label="Submit" />

// jsxQuoteStyle: "single"
<button onClick={handleClick} label='Submit' />

尾随逗号

{
  "javascript": {
    "formatter": {
      "trailingCommas": "all"  // "all", "es5", 或 "none"
    }
  }
}

示例：

// "all"
const obj = {
  a: 1,
  b: 2,
};

function fn(
  arg1,
  arg2,
) {}

// "es5"
const obj = {
  a: 1,
  b: 2,
};

function fn(
  arg1,
  arg2  // 无逗号（非 ES5）
) {}

// "none"
const obj = {
  a: 1,
  b: 2
};

分号

{
  "javascript": {
    "formatter": {
      "semicolons": "always"  // "always" 或 "asNeeded"
    }
  }
}

示例：

// "always"
const x = 1;
const y = 2;

// "asNeeded"
const x = 1
const y = 2

箭头函数括号

{
  "javascript": {
    "formatter": {
      "arrowParentheses": "always"  // "always" 或 "asNeeded"
    }
  }
}

示例：

// "always"
const fn = (x) => x * 2;
const single = (item) => item;

// "asNeeded"
const fn = x => x * 2;
const single = item => item;
const multi = (a, b) => a + b;  // 仍然需要括号

括号间距

{
  "javascript": {
    "formatter": {
      "bracketSpacing": true  // true 或 false
    }
  }
}

示例：

// bracketSpacing: true
const obj = { a: 1, b: 2 };

// bracketSpacing: false
const obj = {a: 1, b: 2};

括号同一行

{
  "javascript": {
    "formatter": {
      "bracketSameLine": false  // true 或 false
    }
  }
}

示例：

// bracketSameLine: false
<Button
  onClick={handleClick}
  label="Submit"
>
  Click me
</Button>

// bracketSameLine: true
<Button
  onClick={handleClick}
  label="Submit">
  Click me
</Button>

引号属性

{
  "javascript": {
    "formatter": {
      "quoteProperties": "asNeeded"  // "asNeeded" 或 "preserve"
    }
  }
}

示例：

// "asNeeded"
const obj = {
  validIdentifier: 1,
  'invalid-identifier': 2,
  'needs quotes': 3,
};

// "preserve"
const obj = {
  'validIdentifier': 1,
  'invalid-identifier': 2,
  'needs quotes': 3,
};

JSON 格式化

{
  "json": {
    "formatter": {
      "enabled": true,
      "indentStyle": "space",
      "indentWidth": 2,
      "lineWidth": 80,
      "trailingCommas": "none"
    }
  }
}

注意：JSON 不支持尾随逗号，所以总是使用 “none”。

CSS 格式化

{
  "css": {
    "formatter": {
      "enabled": true,
      "indentStyle": "space",
      "indentWidth": 2,
      "lineWidth": 80,
      "quoteStyle": "double"
    }
  }
}

常见配置

Prettier-like 配置

{
  "formatter": {
    "enabled": true,
    "indentStyle": "space",
    "indentWidth": 2,
    "lineWidth": 80
  },
  "javascript": {
    "formatter": {
      "quoteStyle": "double",
      "trailingCommas": "es5",
      "semicolons": "always",
      "arrowParentheses": "always",
      "bracketSpacing": true,
      "bracketSameLine": false
    }
  }
}

Standard/XO 风格

{
  "formatter": {
    "enabled": true,
    "indentStyle": "space",
    "indentWidth": 2,
    "lineWidth": 100
  },
  "javascript": {
    "formatter": {
      "quoteStyle": "single",
      "trailingCommas": "none",
      "semicolons": "asNeeded",
      "arrowParentheses": "asNeeded",
      "bracketSpacing": true
    }
  }
}

Google 风格

{
  "formatter": {
    "enabled": true,
    "indentStyle": "space",
    "indentWidth": 2,
    "lineWidth": 80
  },
  "javascript": {
    "formatter": {
      "quoteStyle": "single",
      "trailingCommas": "all",
      "semicolons": "always",
      "arrowParentheses": "always"
    }
  }
}

Airbnb 风格

{
  "formatter": {
    "enabled": true,
    "indentStyle": "space",
    "indentWidth": 2,
    "lineWidth": 100
  },
  "javascript": {
    "formatter": {
      "quoteStyle": "single",
      "jsxQuoteStyle": "double",
      "trailingCommas": "all",
      "semicolons": "always",
      "arrowParentheses": "always",
      "bracketSpacing": true
    }
  }
}

忽略格式化

忽略代码块

// biome-ignore format: 保留特定格式化
const matrix = [
  [1, 0, 0],
  [0, 1, 0],
  [0, 0, 1]
];

// biome-ignore format: ASCII 艺术
const banner = `
  ╔═══════════════╗
  ║   Welcome!    ║
  ╚═══════════════╝
`;

忽略文件

在 biome.json 中：

{
  "formatter": {
    "ignore": [
      "**/generated/**",
      "**/*.min.js",
      "**/dist/**"
    ]
  }
}

或使用 files.ignore 同时忽略代码检查和格式化：

{
  "files": {
    "ignore": [
      "**/node_modules/",
      "**/dist/",
      "**/*.min.js"
    ]
  }
}

行宽策略

保守（80列）

适合代码审查、并排差异：

{
  "formatter": {
    "lineWidth": 80
  }
}

平衡（100-120列）

大多数项目的现代标准：

{
  "formatter": {
    "lineWidth": 100
  }
}

宽松（120+列）

适合拥有大屏幕的团队：

{
  "formatter": {
    "lineWidth": 120
  }
}

缩进策略

空格（推荐）

{
  "formatter": {
    "indentStyle": "space",
    "indentWidth": 2  // 或 4
  }
}

优点：

  • 在所有编辑器中一致
  • 更适合代码审查
  • JavaScript 生态系统的标准

制表符

{
  "formatter": {
    "indentStyle": "tab"
  }
}

优点：

  • 用户可以设置首选宽度
  • 文件大小更小
  • 可访问性好处

从 Prettier 迁移

比较配置

Prettier .prettierrc.json：

{
  "semi": true,
  "singleQuote": true,
  "tabWidth": 2,
  "trailingComma": "all",
  "printWidth": 80
}

等效的 Biome 配置：

{
  "formatter": {
    "indentWidth": 2,
    "lineWidth": 80
  },
  "javascript": {
    "formatter": {
      "semicolons": "always",
      "quoteStyle": "single",
      "trailingCommas": "all"
    }
  }
}

迁移步骤

  1. 安装 Biome：
npm install -D @biomejs/biome
  1. 创建配置：
npx biome init

  1. 匹配 Prettier 设置：更新 biome.json 与等效配置

  2. 格式化代码库：

npx biome format --write .
  1. 更新脚本：
{
  "scripts": {
    "format": "biome format --write .",
    "format:check": "biome format ."
  }
}
  1. 删除 Prettier（验证后）：
npm uninstall prettier
rm .prettierrc.json .prettierignore

最佳实践

  1. 一致配置 - 所有包使用相同设置
  2. 平衡行宽 - 80-120 基于团队偏好
  3. 使用空格 - 比制表符更适合 JavaScript
  4. 在 CI 中启用 - 在管道中检查格式化
  5. 预提交钩子 - 提交前自动格式化
  6. 记录选择 - 向团队解释配置决策
  7. 忽略生成文件 - 不格式化构建输出
  8. 增量格式化 - 使用 --changed 处理大型代码库
  9. 编辑器集成 - 安装 IDE 的 Biome 扩展
  10. 审查差异 - 提交前检查格式化更改

常见陷阱

  1. 配置冲突 - 多个配置有不同设置
  2. 格式化生成代码 - 浪费在构建输出上的时间
  3. 行宽太严格 - 60 或更少太限制
  4. 混合制表符和空格 - 不一致的缩进
  5. 无 CI 检查 - 不在管道中强制执行格式化
  6. 错误的文件模式 - 忽略应该格式化的文件
  7. 无编辑器设置 - 手动运行格式化命令
  8. 大型提交 - 一次性格式化整个代码库
  9. 忽略错误 - formatWithErrors 隐藏语法问题
  10. 无团队协议 - 个人偏好导致冲突

高级主题

每语言覆盖

{
  "formatter": {
    "indentWidth": 2
  },
  "overrides": [
    {
      "include": ["**/*.json"],
      "formatter": {
        "lineWidth": 120
      }
    },
    {
      "include": ["**/*.md"],
      "formatter": {
        "lineWidth": 80
      }
    }
  ]
}

条件格式化

仅格式化更改的文件：

# Git 更改文件
biome format --write --changed

# 特定提交范围
biome format --write --since=main

编辑器集成

VS Code settings.json：

{
  "editor.defaultFormatter": "biomejs.biome",
  "editor.formatOnSave": true,
  "[javascript]": {
    "editor.defaultFormatter": "biomejs.biome"
  },
  "[typescript]": {
    "editor.defaultFormatter": "biomejs.biome"
  },
  "[json]": {
    "editor.defaultFormatter": "biomejs.biome"
  }
}

单仓库设置

根 biome.json：

{
  "formatter": {
    "enabled": true,
    "indentWidth": 2,
    "lineWidth": 100
  },
  "javascript": {
    "formatter": {
      "quoteStyle": "single",
      "trailingCommas": "all"
    }
  }
}

包特定覆盖：

{
  "extends": ["../../biome.json"],
  "formatter": {
    "lineWidth": 120
  }
}

故障排除

文件未被格式化

检查：

  1. formatter.enabled 为 true
  2. 文件扩展名受支持
  3. 文件不在忽略模式中
  4. 版本控制系统集成未排除它

格式化冲突

如果格式化不断变化：

  1. 确保单一 biome.json 作为真实来源
  2. 更新所有团队成员的 Biome 版本
  3. 运行 biome migrate 更新配置
  4. 清除编辑器缓存并重启

性能问题

加速格式化：

  1. 使用 --changed 处理大型仓库
  2. 忽略 node_modules 和 dist
  3. 更新到最新 Biome 版本
  4. 使用版本控制系统集成

何时使用此技能

  • 为项目设置代码格式化
  • 从 Prettier 迁移到 Biome
  • 建立团队代码风格标准
  • 为特定框架配置格式化器
  • 故障排除格式化问题
  • 优化格式化性能
  • 将格式化集成到 CI/CD
  • 培训团队代码风格