Biome 配置与规则（Nuvraxis 单仓库）

用于 Nuvraxis 单仓库的 Biome 2.5 设置与规则——包含根级 biome.json、VCS 忽略、格式化器设置、推荐的预设（含 a11y 和 react/next 领域）、Nursery 策略、导入排序、覆盖配置、每个包的嵌套配置、本地 biome check --write、CI 中的 biome ci、VS Code 设置以及从 ESLint/Prettier 迁移。

Biome 配置与规则（Nuvraxis 单仓库）是什么？

这是一个针对 Nuvraxis 单仓库定制的 Biome 配置指南，帮助开发者统一管理和自动化 JavaScript/TypeScript 项目的格式化与代码检查。该技能详细说明了如何设置根级 biome.json 文件，包括固定 $schema 版本、配置 VCS 忽略规则（如 .next、dist 等构建输出）、格式化器参数（2 空格、100 宽度、LF 换行等）、以及启用带有 a11y（错误级别）与 react/next 领域的推荐预设。它还涵盖了关闭 Nursery 规则（避免 CI 因升级中断）、用 assist 自动排序导入、按 glob 覆盖测试文件规则、以及通过 "extends": "//" 让子包继承根配置的最佳实践。此外，该技能还指导本地使用 biome check --write、CI 中使用 biome ci 并报告 GitHub 注释、VS Code 设置为默认格式化器并在保存时自动修复，以及从 ESLint/Prettier 完整迁移的步骤。它适用于所有包含 biome.json、使用 @biomejs/biome、或存在旧 lint 配置文件的仓库。

兼容平台✓Claude Code~Codex CLI~Cursor

npx skills add https://github.com/Nuvraxis/nuvraxis-plugins/tree/HEAD/plugins/nuvraxis-frontend/skills/biome

文档

Biome

Biome 是 JS、TS、JSX、JSON 和 CSS 的唯一格式化器和检查器。SCSS 是例外：Biome 2.5 无法解析它，因此 stylelint 负责处理 .scss（参见 scss-bem）。没有 ESLint，没有 Prettier。

模板的根目录 biome.json 是真理之源。一个插件钩子在 Claude 每次编辑文件后，当目标文件上方存在 biome.json 时，运行 pnpm exec biome check --write <file>。

规则

一个根目录 biome.json，schema 固定到已安装版本。 "$schema": "https://biomejs.dev/schemas/2.5.15/schema.json"，并且 @biomejs/biome 在工作空间目录中固定到相同版本。不匹配的 schema 会在编辑器中隐藏未知或已重命名的选项。升级时，运行 pnpm exec biome migrate --write 并更新两者。
让 git 决定忽略什么：vcs.useIgnoreFile: true。 然后通过在 files.includes 中使用 !! 强制忽略构建输出（!!**/.next、!!**/.turbo、!!**/dist、!!**/coverage），这也会阻止 Biome 扫描这些文件夹。单个 ! 排除处理但仍会索引。files.ignoreUnknown: true 防止报告 .scss 和其他不支持的文件的错误。
格式化器：2 空格、宽度 100、LF、双引号、分号、尾随逗号。 这些对于每个仓库都是固定的，因此差异不会因样式产生冲突。不要添加每个包的格式化器覆盖。
检查器：preset: "recommended"，a11y: "error"，领域 react 和 next 设为 recommended。 rules.recommended: true 是旧拼写，已弃用：请使用 rules.preset。a11y 设为 error，因为 nuvui 处理其自身组件的可访问性，因此剩下的（alt、标签、在你自己的标记中的按钮类型）必须正确。next 领域添加了例如 noImgElement 等规则；react 添加了 hooks 规则。
Nursery 保持关闭。 Nursery 规则在补丁版本之间会变化，可能在 Biome 升级时破坏 CI。如果有意启用某个规则，请按名称启用，并附上原因注释，同时在每次升级时重新检查。
noConsole 给出警告，但允许 error 和 warn。 结构化错误日志（instrumentation.ts）使用 console.error；零散的 console.log 会被捕获。
使用 assist 排序导入，不要手动。 assist.actions.source.organizeImports: "on"。biome check --write 会应用它；biome ci 会因未排序导入而失败。
按 glob 覆盖，用于测试文件等。 模板仅为 *.test.ts(x) / *.test-d.ts 启用 test 领域。其他文件类型的差异也放在那里，而不是放在单独的配置中。
仅当包真正不同时才使用嵌套配置，并且它们继承根配置。
```
// packages/legacy-widget/biome.json
{ "extends": "//", "linter": { "rules": { "style": { "noNonNullAssertion": "off" } } } }
```
"extends": "//" 表示“根配置”，并隐含 "root": false。任何其他嵌套配置必须设置 "root": false。我们不使用共享的 @repo/biome-config 包：根文件加上 // 就足够了，无需构建或依赖。
本地使用 biome check --write；CI 中使用 biome ci。 pnpm lint 运行 biome check .（不写入）；pnpm lint:fix 运行 biome check --write .。CI 运行 pnpm exec biome ci --reporter=github .，从不写入，对格式化、检查和导入顺序失败，并注释 PR。只有当完整运行变慢时才添加 --changed --since=origin/main；目前只需几毫秒。
抑制单行，并附上原因。
```
// biome-ignore lint/suspicious/noExplicitAny: third-party callback typed as any upstream
```
永远不要为了通过一个文件而在整个仓库范围内禁用规则。如果规则对整个仓库来说是错误的，请在其自己的提交中修改 biome.json，并附上原因。
修复常见的，而不是静默它们。
- useImportType：运行修复；它是 verbatimModuleSyntax 所要求的。
- noExplicitAny：使用 unknown 并解析（参见 typescript-production）。
- useButtonType、noSvgWithoutTitle、useAltText：真正的可访问性缺陷。
- noImgElement：使用 next/image。
- useExhaustiveDependencies：修复依赖列表或将值移出组件。
VS Code：Biome 是默认格式化器，保存时修复。 模板的 .vscode/settings.json 设置 editor.defaultFormatter: "biomejs.biome"，保存时启用 source.fixAll.biome 和 source.organizeImports.biome，并设置 biome.requireConfiguration: true 以使扩展在不包含 Biome 的仓库中保持安静。SCSS 保留 stylelint 扩展。在 .vscode/extensions.json 中推荐两者。
从 ESLint/Prettier 迁移：迁移，然后删除。 参见 references/migration.md。最终状态：没有 eslint*、prettier* 或 @typescript-eslint/* 包，没有 .eslintrc*、eslint.config.*、.prettierrc*、.prettierignore。

Biome 不覆盖的内容

文件	工具
`.scss`	stylelint (`scss-bem`)
`.yaml`（工作流、Helm）	actionlint 用于工作流；`helm lint` + kubeconform 用于图表
`.md`	无强制执行
类型错误	`tsc --noEmit`（`pnpm typecheck`）

验证

pnpm lint                               # biome check . && stylelint
pnpm exec biome ci --reporter=github .  # 这是 CI 运行的内容
pnpm exec biome rage                    # 打印解析后的配置，如果某些内容看起来被忽略了

Biome 配置与规则（Nuvraxis 单仓库）