# 生物群系针对 JavaScript、TypeScript、JSX、CSS 和 GraphQL 的快速、统一的 linting、格式化和导入组织。 Biome 2.4 提供类型感知 linting，无需 TypeScript 编译器、用于自定义规则的 GritQL 插件以及基于域的规则分组。单个二进制文件，默认零配置，97% Prettier 兼容性。 ## 关键规则 ### 始终使用“生物群系检查”，而不是单独的 lint + 格式 “biome check”一次性运行格式化程序、linter 和导入管理器。切勿在 CI 中单独调用“biome lint”和“biome format” - 使用“biome check”（或用于 CI 模式的“biome ci”）。 ### biome.json 位于项目根目录每个项目的根目录下都需要一个“biome.json”。 Monorepo 包使用带有 `"extends": "//"` 的嵌套配置来从 root 继承。切勿使用像“"extends": ["../../biome.json"]`这样的相对路径。 ### 使用 `--write` 来应用修复，而不是 `--fix` 生物群落检查--写入。 # 应用安全修复生物群落检查 --write --unsafe 。 # 应用所有修复（查看更改） ### 固定确切版本并在升级后迁移 pnpm add --save-dev --save-exact @biomejs/biome@latest pnpm 生物群落迁移 --write ## 快速入门 pnpm add --save-dev --save-exact @biomejs/biome pnpm biome init # 使用推荐规则创建默认的 biome.json ### IDE 设置 **VS Code** \- 安装 `biomejs.biome` 扩展： { "editor.defaultFormatter": "biomejs.biome", “editor.formatOnSave”：true， “editor.codeActionsOnSave”：{ "source.organizeImports.biome": "显式" } } **Zed** \- 原生可用的生物群落扩展。 `inline_config` 功能 (v2.4) 允许编辑者覆盖规则而不影响 `biome.json`： { “格式化程序”：{“语言服务器”：{“名称”：“生物群落”}}， “lsp”：{ “生物群系”：{ “设置”：{ “内联配置”：{ “linter”：{“规则”：{“可疑”：{“noConsole”：“关闭”} } } } } } } } ### CI 集成 pnpm 生物群落 ci 。 # 无写入，错误时非零退出 pnpm 生物群系 ci --reporter=default --reporter=github 。 # GitHub Actions 注释 ## 配置（biome.json） ### React/TypeScript 项目的推荐配置 { "$schema": "./node_modules/@biomejs/biome/configuration_schema.json", “VCS”：{ “启用”：正确， “clientKind”：“git”， “useIgnoreFile”：true }, “文件”：{ “包括”：[ “src/**/*.ts”、“src/**/*.tsx”、 “测试/**/*.ts”，“**/*.config.ts”，“**/*.json” ], “忽略”：[ “*.d.ts”、“**/生成”、“**/components/ui” ] }, “格式化程序”：{ “启用”：正确， "indentStyle": "空格", “缩进宽度”：2， “线宽”：120 }, “短绒”：{ “启用”：正确， “规则”：{“推荐”：true }， "domains": { "react": "推荐" } }, “javascript”：{ “格式化程序”：{“quoteStyle”：“双”} }, “协助”：{ “启用”：正确， “行动”：{ "source": { "organizeImports": "on" } } } } ### 格式化选项关键选项：`indentStyle` (`"space"`/`"tab"`)、`indentWidth`、`lineWidth`、`lineEnding` (`"lf"`/`"crlf"`)、`trailingNewline`。 JS 特定：`quoteStyle`、`trailingCommas`、`分号`、`arrowParentheses`、`bracketSpacing`。 ### Linter规则配置规则使用严重级别“错误”、“警告”、“信息”或“关闭”。有些接受选项： { “短绒”：{ “规则”：{ “推荐”：正确， “风格”：{ “noRestrictedGlobals”：{ “级别”：“错误”， “选项”：{ “拒绝全局”：{ "Buffer": "使用 Uint8Array 来实现浏览器兼容性。" } } }, “useComponentExportOnlyModules”：“关闭” } } } } ### 导入组织者导入管理器（Biome Assist）合并重复项，按距离排序，并支持自定义分组： { “协助”：{ “启用”：正确， “行动”：{ “来源”：{ “组织进口”：{ “级别”：“开”， “选项”：{ “组”：[ {“源”：“内置”}， {“来源”：“外部”}， { "source": "内部", "match": "@company/*" }, {“来源”：“相对”} ] } } } } } } ### Monorepo 配置根“biome.json”保存共享配置。包配置继承 `"extends": "//"`： { "$schema": "../../node_modules/@biomejs/biome/configuration_schema.json", “扩展”：“//” } 通过在 `"extends": "//"` 旁边添加 `linter.rules` 部分来覆盖每个包的特定规则。 ### 配置文件发现 (v2.4) 搜索顺序：`biome.json` -> `biome.jsonc` -> `.biome.json` -> `.biome.jsonc` -> 平台配置主目录（Linux 上为`~/.config/biome`，macOS 上为`~/Library/Application Support/biome`）。 ## 域名域按技术对 lint 规则进行分组。仅启用您的堆栈所需的内容： { “短绒”：{ “域”：{ “反应”：“推荐”， "下一个": "推荐", “测试”：“推荐”， “类型”：“全部” } } } 域名 |目的|自动检测 ---|---|--- `反应` | React hooks、JSX 模式 | `react` 依赖 `下一个` | Next.js 特定规则 | `下一个 >= 14.0.0` `固体` | Solid.js 规则 | `solid-js` 依赖项 `测试` |测试最佳实践（任何框架）| - `剧作家` |剧作家考试规则| `@playwright/测试` `项目` |跨文件分析（noImportCycles、noUnresolvedImports）| - `类型` |类型推断规则（noFloatingPromises、noMisusedPromises）| - **激活级别：** `“推荐”`（仅限稳定规则）、“所有”（包括托儿所）、“无”（禁用）。 “project”域启用需要模块图的规则。 “types”域 (v2.4) 支持需要类型推断的规则。两者都会触发文件扫描，从而增加少量开销。 ## 类型感知 Linting Biome 2.0 引入了类型感知 linting，无需 TypeScript 编译器。 Biome 在 Rust 中有自己的类型推断引擎 - 不需要“typescript”依赖。 ### 它是如何工作的启用“types”域以激活文件扫描和类型推断。与 typescript-eslint 相比，性能影响很小，因为推理是本机运行的。 ### 关键规则规则|它捕获什么 ---|--- `没有浮动承诺` |未处理的承诺（缺少等待/返回/无效） `noMisusedPromises` |条件语句、数组回调中的 Promise `useAwaitThenable` |等待非thenable值 `没有不必要的条件` |条件始终为真/假 `useRegexpExec` | `string.match()` 其中 `regexp.exec()` 更好 `使用查找` | `array.filter()[0]` 而不是 `array.find()` `useArraySortCompare` |没有比较函数的 Array.sort() ### noFloatingPromises 最有影响力的类型感知规则。检测未处理的承诺： // 错误：浮动承诺异步函数 loadData() { 获取（“/api/数据”）； } // 有效：等待异步函数 loadData() { 等待获取（“/api/data”）； } // 有效：显式作废（即发即弃）异步函数 loadData() { 无效获取（“/ api /数据”）; } 与 typescript-eslint 相比，检测到约 75% 的案例，从而改进了每个版本。 ### 与 typescript-eslint 的限制 * 复杂的泛型类型推断可能会错过一些情况 * 不是一个完整的类型检查器 - 处理常见模式，而不是每种边缘情况 * 规则仍处于萌芽状态 - 预计每个版本都会有所改进 * 主要性能优势：基于 tsc 的 linting 时间的一小部分 ## GritQL 自定义规则 GritQL 是一种用于自定义 lint 规则的声明式模式匹配语言。创建 `.grit` 文件并将它们注册为插件。 { "plugins": ["./lint-rules/no-object-assign.grit"] } ### 示例 **禁止`Object.assign`:** `$fn($args)` 其中 { $fn <: `对象.分配`, 注册诊断（跨度 = $fn, message = "更喜欢对象传播而不是`Object.assign()`" ） } **CSS - 强制颜色类别：** 语言CSS； `$selector { $props }` 其中 { $props <: 包含 `color: $color` 作为 $rule, 不是 $selector <: r"\.color-.*", 注册诊断（跨度=$规则， message =“不要设置明确的颜色。请改用`.color-*`类。” ） } ### 插件API `register_diagnostic()` 参数： * `严重性` \- `"提示"`、`"信息"`、`"警告"`、`"错误"` (默认值：`"错误"`) * `message`（必需）- 诊断消息 * `span` (必需) - 要突出显示的语法节点支持的目标语言：JavaScript（默认）、CSS、JSON (v2.4)。使用“biome lint --profile-rules”进行配置文件。 ## 抑制模式 ### 单行 // biome-ignore lint/suspicious/noConsole：调试所需 console.log("调试信息"); ### 文件级 // biome-ignore-all lint/suspicious/noConsole: 记录器模块 ### 范围 // biome-ignore-start lint/style/useConst：遗留代码设 x = 1；设 y = 2； // 生物群系忽略结束 lint/style/useConst 常量 a = 4; // 该行已被检查 `biome-ignore-end` 是可选的 - 忽略抑制直到文件末尾。生物群落需要冒号后的解释文本。 ## 迁移 ### 来自 ESLint pnpm 生物群系迁移 eslint --write pnpm biome migrate eslint --write --include-inspired # 包含不相同的规则支持传统和平面配置、“扩展”分辨率、插件（typescript-eslint、react、jsx-a11y、unicorn）、“.eslintignore”。 ### 来自更漂亮 pnpm 生物群落迁移更漂亮 --write 映射`tabWidth` -> `indentWidth`、`useTabs` -> `indentStyle`、`singleQuote` -> `quoteStyle`、`trailingComma` -> `trailingCommas`。 ### 来自 ESLint + Prettier 组合 pnpm 生物群系迁移 eslint --write pnpm 生物群落迁移更漂亮 --write pnpm 删除 eslint prettier eslint-config-prettier eslint-plugin-prettier \ @typescript-eslint/解析器 @typescript-eslint/eslint-plugin rm .eslintrc* .prettierrc* .eslintignore .prettierignore 启用 VCS 集成，因为 ESLint 默认尊重 gitignore： { "vcs": { "enabled": true, "clientKind": "git", "useIgnoreFile": true } } ## CLI 参考 ### 生物群落检查（主要命令）生物群落检查。 # 检查所有文件生物群落检查--写入。 # 应用安全修复生物群落检查 --write --unsafe 。 # 应用所有修复生物群落检查--已更改。 # 仅 VCS 更改的文件生物群系检查——分阶段进行。 # 仅暂存文件 ### 生物群系 ci（CI 模式）生物群落 ci . # 无写入，错误时退出代码生物群系 ci --reporter=github 。 # GitHub 注释生物群系 ci --reporter=sarif --reporter-file=report.sarif 。 #SARIF 输出 ### 生物群系棉绒生物群系 lint --only=suspicious/noDebugger 。 # 单一规则生物群系 lint --skip=project 。 # 跳过域生物群系 lint --only=types 。 # 仅类型感知规则生物群系 lint --error-on-warnings 。 # 警告变成错误 ### 其他命令生物群系格式--write . # 仅限格式生物群系搜索 '`console.$method($args)`' 。 # GritQL 模式搜索 Biome rage # 错误报告的调试信息 biome treatise noFloatingPromises # 解释一条规则 ## 最佳实践 1. **使用`biome check`作为单个命令** \- 结合格式、lint 和导入组织 2. **从`推荐：true`** \- 根据需要禁用单个规则 3. **启用相关域** \- 根据您的堆栈`react`、`next`、`test`、`types` 4. **启用 VCS 集成** \- 尊重 `.gitignore`，启用 `--changed`/`--staged` 5. **在管道中使用`biome ci`** \-从不写入文件，清除退出代码 6. **固定确切版本** \- 避免版本之间出现意外的规则更改 7. **每次升级后运行`biome migrate --write`** 8. **在预提交挂钩中使用`--staged`**：`biome check --staged --write --no-errors-on-unmatched 。` 9. **使用“biome lint --profile-rules”（v2.4）分析慢速规则** 10. **使用 GritQL 插件**来实现特定于项目的模式，而不是全局禁用规则 ## 资源 * **Biome 文档**： * **Biome GitHub**： * **GritQL 文档**： * **Biome v2 博客**： * **Biome v2.4 博客**： * **迁移指南** : * **规则参考** : * **域** : * **插件** : 有关按类别划分的详细 lint 规则和代码示例，请参阅 [rules-reference.md]()。

生物群落

包含技能