代码格式化-Biome配置与使用
前言 请确保已经配置好EditorConfig：https://a.guoqw.com/工程化/代码格式化-EditorConfig配置与使用.html
为什么 Biome 是 2026 年的首选核心工具？
Biome 由 Rust 编写，是近年来前端工具链演进的集大成者。它将代码格式化（Prettier）、静态分析（ESLint）和自动修复、语法检查（oxlint）等功能整合为一个单一、高性能的工具链。在 2025–2026 年，Biome 已成为主流框架（如 Next.js、Vite、React 19+）的官方推荐工具，其优势体现在：
- 单一依赖：无需安装 Prettier、ESLint、eslint-plugin-react 等多个包，减少 node_modules 体积与依赖冲突风险。
- 极速执行：基于 Rust 的原生编译，启动速度比 ESLint 快 10–50 倍，尤其在大型项目中体验显著提升。
- 开箱即用的规则集：内置现代 JavaScript/TypeScript 规则，支持 JSX、TSX、JSON、CSS、HTML，覆盖全栈前端场景。
- 智能自动修复：不仅能格式化代码，还能智能修复逻辑错误（如未使用的变量、错误的导入），远超传统 ESLint 的能力。
- 与编辑器深度集成：VS Code、JetBrains 系列等主流 IDE 已原生支持 Biome，保存即自动格式化，体验无缝。
VSCode插件安装
安装步骤
- 下载插件：在IDE中安装Biome扩展，请搜索：biomejs.biome
- 注意事项：安装完后请重启IDE，尽量禁用掉ESLint与Prettier插件。
配置文件示例
项目配置（.vscode/settings.json）
主要作用：
指定格式化工具；
项目级禁用prettier、eslint；
与EditorConfig整合
{
// ===== Biome 配置 =====
// 设置 Biome 为默认格式化工具
"editor.defaultFormatter": "biomejs.biome",
// 保存时自动格式化
"editor.formatOnSave": true,
// ===== 针对特定语言的格式化配置 =====
"[javascript]": {
"editor.defaultFormatter": "biomejs.biome"
},
"[javascriptreact]": {
"editor.defaultFormatter": "biomejs.biome"
},
"[typescript]": {
"editor.defaultFormatter": "biomejs.biome"
},
"[typescriptreact]": {
"editor.defaultFormatter": "biomejs.biome"
},
"[json]": {
"editor.defaultFormatter": "biomejs.biome"
},
"[jsonc]": {
"editor.defaultFormatter": "biomejs.biome"
},
"[css]": {
"editor.defaultFormatter": "biomejs.biome"
},
"[vue]": {
"editor.defaultFormatter": "biomejs.biome"
},
// ===== 禁用其他格式化/检查工具（避免冲突）=====
// 禁用 Prettier
"prettier.enable": false,
// 禁用 ESLint 格式化（如果安装了 ESLint 扩展）
"eslint.enable": false,
// ===== Biome 扩展配置 =====
// 启用 Biome 扩展
"biome.enabled": true,
// 配置文件路径（默认会自动检测）
"biome.configPath": "./biome.jsonc",
// 文件末尾插入新行（与 EditorConfig 一致）
"files.insertFinalNewline": true,
// 删除行尾空白（与 EditorConfig 一致）
"files.trimTrailingWhitespace": true,
// 文件编码（与 EditorConfig 一致）
"files.encoding": "utf8",
// 行尾字符（与 EditorConfig 一致）
"files.eol": "\n"
}基础配置（biome.jsonc）
主要作用：在维持最基本整洁格式的情况下减少对历史代码逻辑的影响
{
"$schema": "https://biomejs.dev/schemas/2.4.4/schema.json",
// Biome 配置文件
// 官方文档: https://biomejs.dev/reference/configuration/
// 微博智搜前端【自动化代码格式统一、代码问题修复】说明文档：https://alidocs.dingtalk.com/i/nodes/OG9lyrgJPXxlBmLlfXa211X9JzN67Mw4
// 代码检查器配置
"linter": {
"enabled": true,
"rules": {
// 推荐规则集
"recommended": true,
// 复杂度相关规则
"complexity": {
// 禁止 forEach 循环（关闭，项目中大量使用）
"noForEach": "off",
// 使用 Date.now()（关闭，历史代码兼容）
"useDateNow": "off",
// 使用箭头函数（关闭，历史代码兼容）
"useArrowFunction": "off",
// 禁止使用 arguments（关闭，历史代码兼容）
"noArguments": "off"
},
// 正确性相关规则
"correctness": {
// 禁止未使用的变量（警告级别）
"noUnusedVariables": "warn",
// 禁止未使用的导入（警告级别）
"noUnusedImports": "warn",
// 禁止未使用的私有类成员
"noUnusedPrivateClassMembers": "warn",
// 禁止不可达代码（警告级别，历史代码兼容）
"noUnreachable": "warn",
// 禁止内部声明（关闭，历史代码使用 var）
"noInnerDeclarations": "off",
// parseInt 需要 radix 参数（关闭，历史代码兼容）
"useParseIntRadix": "off"
},
// 代码风格相关规则
"style": {
// 使用 const 声明不会被重新赋值的变量（警告级别）
"useConst": "warn",
// 使用模板字面量而非字符串拼接（关闭，项目中大量使用字符串拼接）
"useTemplate": "off",
// 禁止非空断言
"noNonNullAssertion": "off",
// 使用 Number 的静态方法（关闭）
"useNumberNamespace": "off"
},
// 可疑代码相关规则
"suspicious": {
// 禁止显式的 any 类型
"noExplicitAny": "off",
// 禁止重复的 case 标签
"noDuplicateCase": "error",
// 禁止双等号比较（关闭，历史代码大量使用）
"noDoubleEquals": "off",
// 禁止 console 语句（开发时关闭）
"noConsole": "off",
// 禁止 debugger 语句
"noDebugger": "warn",
// 禁止无用的转义字符（关闭，历史代码兼容）
"noUselessEscapeInString": "off",
// 禁止在表达式中赋值（关闭，历史代码兼容）
"noAssignInExpressions": "off"
},
// 性能相关规则
"performance": {
// 禁止在循环中使用 delete（关闭）
"noDelete": "off"
},
// 安全相关规则
"security": {
// 禁止 dangerouslySetInnerHTML（关闭）
"noDangerouslySetInnerHtml": "off"
}
}
},
// 代码格式化配置
"formatter": {
"enabled": true,
// 缩进风格：与 EditorConfig 保持一致
"indentStyle": "space",
// 缩进宽度：与 EditorConfig 保持一致
"indentWidth": 2,
// 行宽限制
"lineWidth": 120,
// 行尾字符：与 EditorConfig 保持一致
"lineEnding": "lf"
},
// JavaScript 特定配置
"javascript": {
"formatter": {
// 使用单引号
"quoteStyle": "single",
// 不使用尾随逗号（兼容旧代码风格）
"trailingCommas": "none",
// 不使用分号（根据项目现有风格）
"semicolons": "asNeeded",
// 箭头函数参数括号：仅在需要时使用
"arrowParentheses": "asNeeded"
},
// 全局变量配置
"globals": [
"wbx",
"WBXEnvironment",
"getApp",
"getCurrentPages",
"console",
"setTimeout",
"clearTimeout",
"setInterval",
"clearInterval",
"Promise",
"JSON",
"Math",
"Date",
"parseInt",
"parseFloat",
"isNaN",
"isFinite",
"decodeURIComponent",
"encodeURIComponent"
]
},
// JSON 特定配置
"json": {
"formatter": {
// 不使用尾随逗号
"trailingCommas": "none"
},
"parser": {
// 允许注释
"allowComments": true,
// 允许尾随逗号
"allowTrailingCommas": true
}
},
// CSS 特定配置
"css": {
"formatter": {
"enabled": true,
"indentStyle": "space",
"indentWidth": 2,
"lineWidth": 120
},
"linter": {
"enabled": true
}
},
// 注意：html 配置需要 Biome 2.3+ 版本
// WBoxStudio 内置的 Biome 扩展版本较旧，不支持此配置
// 命令行格式化（npx @biomejs/biome）会使用新版 Biome 2.4.4
"html": {
"experimentalFullSupportEnabled": true,
"formatter": {
"enabled": true,
"indentStyle": "space",
"indentWidth": 2,
"lineWidth": 120,
"attributePosition": "multiline"
}
},
// 文件配置
"files": {
// 包含的文件模式
"includes": [
"src/**/*.js",
"src/**/*.ts",
"src/**/*.jsx",
"src/**/*.tsx",
"src/**/*.vue",
"src/**/*.json",
"src/**/*.css",
"scripts/**/*.js",
"measure/**/*.js",
"*.js",
"*.ts",
"*.json"
],
// 最大文件大小（字节）
"maxSize": 2097152
},
// VCS 配置
"vcs": {
"enabled": true,
"clientKind": "git",
// 使用 .gitignore 文件
"useIgnoreFile": true,
// 默认分支
"defaultBranch": "master"
},
// 辅助功能配置（替代 organizeImports）
"assist": {
"enabled": true
}
}与EditorConfig的集成
- 优先级规则：
- biome配置优先级高于EditorConfig，若两者冲突以biome为准。
- 差异
- 使用者对差异无感知
典型使用场景
- Git提交前自动格式化：
# 在lefthook.yml中添加脚本
# 提交前的代码检查
pre-commit:
# 使用 Biome 进行代码检查和格式化
biome-check:
glob: "*.{js,ts,vue,jsx,tsx,json,css}"
run: npx @biomejs/biome check --write {staged_files}
stage_fixed: true
# 在package.json中添加脚本
"husky": {
"hooks": {
"pre-commit": "biome-check --staged"
}
}VS Code快捷键：
格式化当前文件：Shift + Alt + F
格式化保存时自动执行：需确保设置中开启editor.formatOnSave。
故障排除
配置未生效：
- 检查配置文件名称是否正确（biome.jsonc）。
- 确保插件未被禁用（VS Code扩展管理器中勾选biome）。
与ESLint冲突：
- 在.vscode/settings.json配置中设置禁用ESLint：
版本兼容性问题：
- 更新biome至最新版本或与项目依赖版本对齐。
效果
- 自动格式化：保存文件时自动按配置规则格式化代码。
- 减少冲突：团队协作中消除因格式差异导致的Git冲突。
- 提高效率：手写代码；特别是后期迭代代码、排查问题的效率