Biome 代码格式化和检查工具

了解如何使用 Biome 进行代码格式化、Lint 检查和配置管理

Biome 使用指南

Biome 是一个快速的代码格式化和 Lint 工具，替代了传统的 ESLint + Prettier 组合。本项目使用 Biome 来保持代码质量和一致性。

🚀 快速开始

基本命令

# 格式化代码
bun format

# 运行 Lint 检查
bun lint

# 自动修复可修复的 Lint 问题
bun lint --fix

# 自动修复（包括不安全的修复）
bunx @biomejs/biome lint . --fix --unsafe

# 类型检查
bun type-check

# 一键检查所有配置
bun check-config

在 VS Code 中使用

安装 Biome 扩展：Biome
扩展会自动读取项目中的 biome.json 配置
保存时自动格式化代码
实时显示 Lint 错误和警告

📋 项目配置

我们的 biome.json 配置已经针对项目进行了优化：

已排除的目录

{
  "files": {
    "ignore": [
      "./scripts/**/*",     // 脚本文件
      "node_modules/**/*",  // 依赖包
      "dist/**/*",          // 构建输出
      ".next/**/*",         // Next.js 缓存
      "build/**/*",         // 构建目录
      ".deploy/**/*"        // 部署目录
    ]
  }
}

已关闭的规则

为了适应项目特点，我们关闭了一些严格的规则：

useKeyWithClickEvents: 鼠标事件无需强制键盘事件
useFocusableInteractive: 交互元素无需强制可聚焦
useSemanticElements: 无需强制使用语义元素
noSvgWithoutTitle: SVG 无需强制 title
useButtonType: 按钮无需强制指定 type

代码风格规则

noUnusedFunctionParameters: 允许未使用的函数参数
noNonNullAssertion: 允许非空断言 (!)
noCommaOperator: 允许逗号操作符

复杂度规则

noStaticOnlyClass: 允许只有静态方法的类
noForEach: 允许使用 forEach

安全规则

noDangerouslySetInnerHtml: 允许 dangerouslySetInnerHTML

🛠️ 开发工作流

提交代码前的检查

建议在提交代码前运行：

# 完整检查流程
bun format    # 格式化代码
bun lint      # 检查 Lint 错误
bun type-check # TypeScript 类型检查

或者使用一键检查：

bun check-config  # 运行所有验证

Git Hooks

项目可能配置了 pre-commit hooks，会在提交时自动运行 Biome 检查。

🔧 自定义配置

忽略特定文件

如果需要忽略特定文件，在 biome.json 中添加：

{
  "files": {
    "ignore": [
      "./src/specific-file.ts",
      "./src/legacy/**/*"
    ]
  }
}

覆盖特定规则

如果需要为特定目录或文件类型设置不同规则：

{
  "overrides": [
    {
      "include": ["*.test.ts", "*.spec.ts"],
      "linter": {
        "rules": {
          "suspicious": {
            "noExplicitAny": "off"
          }
        }
      }
    }
  ]
}

内联忽略

对于特定行或代码块，可以使用注释忽略：

// biome-ignore lint/suspicious/noExplicitAny: 这里需要使用 any 类型
const data: any = legacyApi();

/* biome-ignore lint/complexity/noBannedTypes: 遗留代码需要 */
function oldFunction(param: Function) {
  // ...
}

📚 常见问题

Q: 为什么选择 Biome 而不是 ESLint + Prettier？

A: Biome 的优势：

速度更快: 用 Rust 编写，比传统工具快 10-100 倍
配置简单: 一个配置文件包含所有规则
内存占用少: 更高效的内存使用
一致性好: 格式化和 Lint 规则完全兼容

Q: `bun lint` 为什么比 `bun type-check` 快很多？

A: 性能差异原因：

Biome lint 快的原因：

用 Rust 编写，天然支持并行处理
只进行语法检查和代码风格检查
不需要构建完整的类型关系图
针对性优化的规则引擎

TypeScript type-check 慢的原因：

需要分析整个项目的类型关系
构建完整的类型依赖图谱
处理复杂的类型推断和泛型计算
需要解析所有导入的类型定义文件

Q: 可以用 `bun lint` 完全代替 `bun type-check` 吗？

A: 不能完全代替，两者功能互补：

Biome lint 主要检查：

代码风格和语法错误
潜在的 bug 模式（如未使用的变量）
可访问性问题
安全问题（如危险的 innerHTML）

TypeScript type-check 主要检查：

类型兼容性错误
类型推断问题
接口实现完整性
泛型约束违规

建议做法：

开发时优先运行 bun lint 进行快速检查
提交前必须运行 bun lint && bun type-check 确保代码质量
在 CI 中两个命令都要执行

Q: 如何处理 Biome 不支持的 ESLint 插件？

A: 对于 Biome 暂不支持的特定规则，可以：

查看是否有等效的 Biome 规则
在项目中保留 ESLint 处理特定文件
等待 Biome 的功能更新

Q: 代码格式化结果与预期不同怎么办？

A: 检查：

VS Code 是否使用了正确的格式化程序
biome.json 配置是否正确
是否有其他格式化工具冲突

Q: 如何在 CI/CD 中集成 Biome？

A: 在 GitHub Actions 中：

- name: Install dependencies
  run: bun install

- name: Run Biome checks
  run: |
    bun format --check
    bun lint
    bun type-check

🔗 相关资源

💡 最佳实践

保存时格式化: 在 VS Code 中启用 "Format on Save"
提交前检查: 养成运行 bun check-config 的习惯
团队一致性: 确保团队成员都使用相同的 Biome 版本
渐进式采用: 对新代码严格执行，对遗留代码逐步改进
配置文档: 重要的配置更改要在团队内沟通

通过合理使用 Biome，我们可以保持代码的高质量和一致性，提升开发效率！

Biome 代码格式化和检查工具

On this page