名称: biome-configuration 用户可调用: false 描述: 用于 Biome 配置，包括 biome.json 设置、架构版本、VCS 集成和项目组织。允许工具: [Read, Write, Edit, Bash, Glob, Grep]

Biome 配置

掌握 Biome 配置，包括 biome.json 设置、架构版本、VCS 集成和项目组织，以实现最佳的 JavaScript/TypeScript 工具链。

概述

Biome 是一个快速、现代的 JavaScript 和 TypeScript 项目工具链，它将代码检查和格式化结合在一个工具中。它被设计为 ESLint 和 Prettier 的性能替代品，用 Rust 编写以实现最大速度。

安装和设置

基本安装

在项目中安装 Biome：

npm install --save-dev @biomejs/biome
# 或
pnpm add -D @biomejs/biome
# 或
yarn add -D @biomejs/biome

初始化配置

创建基本的 biome.json 配置：

npx biome init

这会在项目根目录中创建 biome.json 文件。

配置文件结构

基本 biome.json

{
  "$schema": "https://biomejs.dev/schemas/1.9.4/schema.json",
  "vcs": {
    "enabled": true,
    "clientKind": "git",
    "useIgnoreFile": true
  },
  "files": {
    "ignoreUnknown": false,
    "ignore": []
  },
  "formatter": {
    "enabled": true,
    "indentStyle": "space",
    "indentWidth": 2,
    "lineWidth": 80
  },
  "linter": {
    "enabled": true,
    "rules": {
      "recommended": true
    }
  },
  "javascript": {
    "formatter": {
      "quoteStyle": "single",
      "trailingCommas": "es5"
    }
  }
}

架构版本控制

始终使用与您的 Biome 安装匹配的正确架构版本：

# 检查 Biome 版本
npx biome --version

# 迁移配置到当前版本
npx biome migrate --write

$schema 字段启用 IDE 自动完成和验证：

{
  "$schema": "https://biomejs.dev/schemas/2.3.6/schema.json"
}

VCS 集成

配置版本控制集成以尊重 .gitignore：

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

选项：

enabled: 启用 VCS 集成
clientKind: “git” 用于 Git 仓库
useIgnoreFile: 尊重 .gitignore 模式
defaultBranch: 操作的默认分支名称

文件管理

文件模式

控制 Biome 处理哪些文件：

{
  "files": {
    "ignoreUnknown": false,
    "ignore": [
      "**/node_modules/**",
      "**/dist/**",
      "**/.next/**",
      "**/build/**",
      "**/.cache/**"
    ],
    "include": ["src/**/*.ts", "src/**/*.tsx"]
  }
}

常见忽略模式

{
  "files": {
    "ignore": [
      "**/node_modules/",
      "**/dist/",
      "**/build/",
      "**/.next/",
      "**/.cache/",
      "**/coverage/",
      "**/*.min.js",
      "**/*.log"
    ]
  }
}

格式化器配置

基本格式化器设置

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

选项：

enabled: 启用/禁用格式化器
formatWithErrors: 即使有语法错误也格式化
indentStyle: “space” 或 “tab”
indentWidth: 空格数量（推荐 2 或 4）
lineEnding: “lf”, “crlf” 或 “cr”
lineWidth: 最大行长度

语言特定格式化

JavaScript/TypeScript

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

JSON

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

代码检查器配置

启用推荐规则

{
  "linter": {
    "enabled": true,
    "rules": {
      "recommended": true
    }
  }
}

规则类别

配置特定的规则组：

{
  "linter": {
    "enabled": true,
    "rules": {
      "recommended": true,
      "a11y": {
        "recommended": true
      },
      "complexity": {
        "recommended": true
      },
      "correctness": {
        "recommended": true
      },
      "performance": {
        "recommended": true
      },
      "security": {
        "recommended": true
      },
      "style": {
        "recommended": true
      },
      "suspicious": {
        "recommended": true
      }
    }
  }
}

细粒度规则控制

启用或禁用特定规则：

{
  "linter": {
    "rules": {
      "recommended": true,
      "suspicious": {
        "noExplicitAny": "error",
        "noConsoleLog": "warn"
      },
      "style": {
        "useConst": "error",
        "noVar": "error"
      }
    }
  }
}

规则级别：

"off": 禁用规则
"warn": 显示警告
"error": 失败检查

单体仓库配置

根配置

{
  "$schema": "https://biomejs.dev/schemas/2.3.6/schema.json",
  "extends": [],
  "files": {
    "ignore": ["**/node_modules/", "**/dist/"]
  },
  "formatter": {
    "enabled": true,
    "indentWidth": 2
  },
  "linter": {
    "enabled": true,
    "rules": {
      "recommended": true
    }
  }
}

包特定覆盖

每个包可以有自己 biome.json：

{
  "$schema": "https://biomejs.dev/schemas/2.3.6/schema.json",
  "extends": ["../../biome.json"],
  "linter": {
    "rules": {
      "suspicious": {
        "noConsoleLog": "off"
      }
    }
  }
}

最佳实践

使用架构 URL - 始终包含 $schema 以支持 IDE
版本管理 - 更新后运行 biome migrate
VCS 集成 - 启用 VCS 以尊重 .gitignore
一致的格式化 - 在整个团队中设置清晰的格式化器规则
规则文档化 - 记录为什么禁用特定规则
单体仓库策略 - 使用扩展共享配置
CI 集成 - 在持续集成中运行 biome ci
预提交钩子 - 提交前验证代码
编辑器集成 - 安装 Biome VSCode/IDE 扩展
定期更新 - 更新 Biome 以获取新功能

常见陷阱

架构不匹配 - 使用过时的架构版本
缺少迁移 - 更新后未运行迁移
过于严格 - 启用所有规则而无团队协议
无 VCS 集成 - 不尊重 gitignore 模式
配置不一致 - 包之间设置不同
忽略警告 - 忽视指示问题的警告
无编辑器设置 - 缺少 IDE 集成以获取实时反馈
行宽过大 - 设置 lineWidth 太高降低可读性
混合引号 - 未强制执行一致的引号风格
无 CI 强制执行 - 不在 CI 管道中运行检查

高级主题

路径覆盖

{
  "overrides": [
    {
      "include": ["scripts/**/*.js"],
      "linter": {
        "rules": {
          "suspicious": {
            "noConsoleLog": "off"
          }
        }
      }
    },
    {
      "include": ["**/*.test.ts"],
      "linter": {
        "rules": {
          "suspicious": {
            "noExplicitAny": "off"
          }
        }
      }
    }
  ]
}

自定义脚本

添加到 package.json：

{
  "scripts": {
    "lint": "biome check .",
    "lint:fix": "biome check --write .",
    "format": "biome format --write .",
    "ci": "biome ci ."
  }
}

CI/CD 集成

# CI 模式（警告时失败）
biome ci .

# 检查而不修复
biome check .

# 自动修复
biome check --write .

# 仅格式化
biome format --write .

何时使用此技能

在新项目中设置 Biome
从 ESLint/Prettier 迁移到 Biome
配置 Biome 用于单体仓库
自定义代码检查和格式化规则
排除 Biome 配置问题
集成 Biome 到 CI/CD 管道
建立团队代码标准
优化 Biome 性能

故障排除

架构版本不匹配

# 错误：架构版本与 CLI 版本不匹配
npx biome migrate --write

文件未被检查

检查：

VCS 集成和 .gitignore
files.ignore 模式
files.include 如果指定
Biome 支持的文件扩展名

规则未应用

验证：

linter.enabled 为 true
规则类别已启用
规则名称正确
无覆盖禁用该规则

性能问题

优化：

使用 files.ignore 处理大目录
启用 VCS 集成
排除生成文件
更新到最新 Biome 版本

名称: biome-configuration 用户可调用: false 描述: 用于 Biome 配置，包括 biome.json 设置、架构版本、VCS 集成和项目组织。 允许工具: [Read, Write, Edit, Bash, Glob, Grep]