Biome
Biome 是 JS、TS、JSX、JSON 和 CSS 的唯一格式化與 lint 工具。SCSS 例外：Biome 2.5 不解析 SCSS，因此 .scss 由 stylelint 處理（請參閱 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可避免 Biome 回報不支援的檔案（如.scss）。 -
格式化器：2 空格、寬度 100、LF、雙引號、分號、尾逗號。 這些設定對每個儲存庫都是固定的，這樣就不會在差異比較中爭論樣式。不要為個別套件新增格式化器覆寫。
-
Lint：
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.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 .，永不寫入，在格式化、lint 和匯入順序不符時失敗，並在 PR 上添加註解。僅在全量執行變慢時才加入--changed --since=origin/main；目前只需毫秒。 -
單行抑制，並附上原因。
// biome-ignore lint/suspicious/noExplicitAny: 第三方回呼型別已由上游定義為 any永遠不要為了讓某個檔案通過而全儲存庫地停用規則。如果某個規則對整個儲存庫來說是錯的，請在它自己的 commit 中修改
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 # 印出解析後的設定（如有內容看似被忽略）
來源
- https://biomejs.dev/reference/configuration/
- https://biomejs.dev/guides/big-projects/
- https://biomejs.dev/linter/domains/
- https://biomejs.dev/linter/rules/
- https://biomejs.dev/reference/cli/
- https://biomejs.dev/reference/vscode/
- https://biomejs.dev/guides/migrate-eslint-prettier/
- https://biomejs.dev/internals/language-support/