biome-linting

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Biome Linting

Biome代码检查

Expert knowledge of Biome's linting capabilities, rule categories, and code quality enforcement for JavaScript and TypeScript projects.

精通Biome针对JavaScript和TypeScript项目的代码检查能力、规则分类及代码质量管控方案。

Overview

概述

Biome's linter provides fast, comprehensive code quality checks with a focus on correctness, performance, security, and best practices. It's designed to catch common bugs and enforce consistent code patterns.

Biome的代码检查工具提供快速、全面的代码质量检测，重点关注正确性、性能、安全性及最佳实践，旨在捕获常见bug并强制执行一致的代码模式。

Core Commands

核心命令

Basic Linting

基础代码检查

bash

undefined

bash

undefined

Check files without fixing

检查文件但不自动修复

biome check .

Check and auto-fix

检查并自动修复

biome check --write .

Check specific files

检查指定文件

biome check src/**/*.ts

CI mode (strict, fails on warnings)

CI模式（严格模式，警告即失败）

biome ci .

undefined

biome ci .

undefined

Command Options

命令选项

bash

undefined

bash

undefined

Verbose output

详细输出

biome check --verbose .

JSON output

JSON格式输出

biome check --json .

Only lint (skip formatting)

仅执行代码检查（跳过格式化）

biome lint .

Apply safe fixes only

仅应用安全修复

biome check --write --unsafe=false .

undefined

biome check --write --unsafe=false .

undefined

Rule Categories

规则分类

Accessibility (a11y)

可访问性（a11y）

Rules for web accessibility and WCAG compliance:

json

{
  "linter": {
    "rules": {
      "a11y": {
        "recommended": true,
        "noAccessKey": "error",
        "noAriaHiddenOnFocusable": "error",
        "noAutofocus": "warn",
        "noBlankTarget": "error",
        "noPositiveTabindex": "error",
        "useAltText": "error",
        "useAnchorContent": "error",
        "useButtonType": "error",
        "useValidAriaProps": "error"
      }
    }
  }
}

Common violations:

Missing alt text on images
Autofocus on form elements
Positive tabindex values
Links without content
Invalid ARIA properties

针对Web可访问性及WCAG合规性的规则：

json

{
  "linter": {
    "rules": {
      "a11y": {
        "recommended": true,
        "noAccessKey": "error",
        "noAriaHiddenOnFocusable": "error",
        "noAutofocus": "warn",
        "noBlankTarget": "error",
        "noPositiveTabindex": "error",
        "useAltText": "error",
        "useAnchorContent": "error",
        "useButtonType": "error",
        "useValidAriaProps": "error"
      }
    }
  }
}

常见违规情况：

图片缺少alt文本
表单元素设置自动聚焦
tabindex值为正数
链接无内容
ARIA属性无效

Complexity

复杂度

Rules to reduce code complexity:

json

{
  "linter": {
    "rules": {
      "complexity": {
        "recommended": true,
        "noBannedTypes": "error",
        "noExcessiveCognitiveComplexity": "warn",
        "noExtraBooleanCast": "error",
        "noMultipleSpacesInRegularExpressionLiterals": "error",
        "noUselessCatch": "error",
        "noUselessConstructor": "error",
        "noUselessEmptyExport": "error",
        "noUselessFragments": "error",
        "noUselessLabel": "error",
        "noUselessRename": "error",
        "noUselessSwitchCase": "error",
        "noWith": "error"
      }
    }
  }
}

用于降低代码复杂度的规则：

json

{
  "linter": {
    "rules": {
      "complexity": {
        "recommended": true,
        "noBannedTypes": "error",
        "noExcessiveCognitiveComplexity": "warn",
        "noExtraBooleanCast": "error",
        "noMultipleSpacesInRegularExpressionLiterals": "error",
        "noUselessCatch": "error",
        "noUselessConstructor": "error",
        "noUselessEmptyExport": "error",
        "noUselessFragments": "error",
        "noUselessLabel": "error",
        "noUselessRename": "error",
        "noUselessSwitchCase": "error",
        "noWith": "error"
      }
    }
  }
}

Correctness

正确性

Rules for code correctness and bug prevention:

json

{
  "linter": {
    "rules": {
      "correctness": {
        "recommended": true,
        "noChildrenProp": "error",
        "noConstAssign": "error",
        "noConstantCondition": "error",
        "noConstructorReturn": "error",
        "noEmptyPattern": "error",
        "noGlobalObjectCalls": "error",
        "noInnerDeclarations": "error",
        "noInvalidConstructorSuper": "error",
        "noNewSymbol": "error",
        "noNonoctalDecimalEscape": "error",
        "noPrecisionLoss": "error",
        "noSelfAssign": "error",
        "noSetterReturn": "error",
        "noSwitchDeclarations": "error",
        "noUndeclaredVariables": "error",
        "noUnreachable": "error",
        "noUnreachableSuper": "error",
        "noUnsafeFinally": "error",
        "noUnsafeOptionalChaining": "error",
        "noUnusedLabels": "error",
        "noUnusedVariables": "error",
        "useIsNan": "error",
        "useValidForDirection": "error",
        "useYield": "error"
      }
    }
  }
}

Critical rules:

```
noUndeclaredVariables
```
: Catch undeclared variables
```
noUnusedVariables
```
: Remove unused code
```
noConstAssign
```
: Prevent const reassignment
```
noUnreachable
```
: Detect unreachable code
```
useIsNan
```
: Use isNaN() for NaN checks

保障代码正确性、预防bug的规则：

json

{
  "linter": {
    "rules": {
      "correctness": {
        "recommended": true,
        "noChildrenProp": "error",
        "noConstAssign": "error",
        "noConstantCondition": "error",
        "noConstructorReturn": "error",
        "noEmptyPattern": "error",
        "noGlobalObjectCalls": "error",
        "noInnerDeclarations": "error",
        "noInvalidConstructorSuper": "error",
        "noNewSymbol": "error",
        "noNonoctalDecimalEscape": "error",
        "noPrecisionLoss": "error",
        "noSelfAssign": "error",
        "noSetterReturn": "error",
        "noSwitchDeclarations": "error",
        "noUndeclaredVariables": "error",
        "noUnreachable": "error",
        "noUnreachableSuper": "error",
        "noUnsafeFinally": "error",
        "noUnsafeOptionalChaining": "error",
        "noUnusedLabels": "error",
        "noUnusedVariables": "error",
        "useIsNan": "error",
        "useValidForDirection": "error",
        "useYield": "error"
      }
    }
  }
}

关键规则：

```
noUndeclaredVariables
```
: 捕获未声明的变量
```
noUnusedVariables
```
: 移除未使用的代码
```
noConstAssign
```
: 禁止对const变量重新赋值
```
noUnreachable
```
: 检测不可达代码
```
useIsNan
```
: 使用isNaN()检查NaN值

Performance

性能

Rules for performance optimization:

json

{
  "linter": {
    "rules": {
      "performance": {
        "recommended": true,
        "noAccumulatingSpread": "warn",
        "noDelete": "error"
      }
    }
  }
}

用于性能优化的规则：

json

{
  "linter": {
    "rules": {
      "performance": {
        "recommended": true,
        "noAccumulatingSpread": "warn",
        "noDelete": "error"
      }
    }
  }
}

Security

安全性

Rules for security best practices:

json

{
  "linter": {
    "rules": {
      "security": {
        "recommended": true,
        "noDangerouslySetInnerHtml": "error",
        "noDangerouslySetInnerHtmlWithChildren": "error",
        "noGlobalEval": "error"
      }
    }
  }
}

Critical security rules:

Prevent XSS via innerHTML
Block eval() usage
Detect security vulnerabilities

遵循安全最佳实践的规则：

json

{
  "linter": {
    "rules": {
      "security": {
        "recommended": true,
        "noDangerouslySetInnerHtml": "error",
        "noDangerouslySetInnerHtmlWithChildren": "error",
        "noGlobalEval": "error"
      }
    }
  }
}

关键安全规则：

防止通过innerHTML产生XSS攻击
禁止使用eval()
检测安全漏洞

Style

代码风格

Code style and consistency rules:

json

{
  "linter": {
    "rules": {
      "style": {
        "recommended": true,
        "noArguments": "error",
        "noCommaOperator": "error",
        "noImplicitBoolean": "warn",
        "noNegationElse": "warn",
        "noNonNullAssertion": "warn",
        "noParameterAssign": "error",
        "noRestrictedGlobals": "error",
        "noShoutyConstants": "warn",
        "noUnusedTemplateLiteral": "error",
        "noVar": "error",
        "useBlockStatements": "warn",
        "useCollapsedElseIf": "warn",
        "useConst": "error",
        "useDefaultParameterLast": "error",
        "useEnumInitializers": "warn",
        "useExponentiationOperator": "error",
        "useFragmentSyntax": "error",
        "useNumericLiterals": "error",
        "useSelfClosingElements": "error",
        "useShorthandArrayType": "error",
        "useSingleVarDeclarator": "error",
        "useTemplate": "warn",
        "useWhile": "error"
      }
    }
  }
}

Key style rules:

```
noVar
```
: Use let/const instead of var
```
useConst
```
: Prefer const for immutable bindings
```
noNonNullAssertion
```
: Avoid ! assertions in TypeScript
```
useTemplate
```
: Prefer template literals

代码风格与一致性规则：

json

{
  "linter": {
    "rules": {
      "style": {
        "recommended": true,
        "noArguments": "error",
        "noCommaOperator": "error",
        "noImplicitBoolean": "warn",
        "noNegationElse": "warn",
        "noNonNullAssertion": "warn",
        "noParameterAssign": "error",
        "noRestrictedGlobals": "error",
        "noShoutyConstants": "warn",
        "noUnusedTemplateLiteral": "error",
        "noVar": "error",
        "useBlockStatements": "warn",
        "useCollapsedElseIf": "warn",
        "useConst": "error",
        "useDefaultParameterLast": "error",
        "useEnumInitializers": "warn",
        "useExponentiationOperator": "error",
        "useFragmentSyntax": "error",
        "useNumericLiterals": "error",
        "useSelfClosingElements": "error",
        "useShorthandArrayType": "error",
        "useSingleVarDeclarator": "error",
        "useTemplate": "warn",
        "useWhile": "error"
      }
    }
  }
}

核心风格规则：

```
noVar
```
: 使用let/const替代var
```
useConst
```
: 优先使用const声明不可变变量
```
noNonNullAssertion
```
: 避免在TypeScript中使用!断言
```
useTemplate
```
: 优先使用模板字符串

Suspicious

可疑代码

Rules for suspicious code patterns:

json

{
  "linter": {
    "rules": {
      "suspicious": {
        "recommended": true,
        "noArrayIndexKey": "warn",
        "noAssignInExpressions": "error",
        "noAsyncPromiseExecutor": "error",
        "noCatchAssign": "error",
        "noClassAssign": "error",
        "noCommentText": "error",
        "noCompareNegZero": "error",
        "noConsoleLog": "warn",
        "noControlCharactersInRegex": "error",
        "noDebugger": "error",
        "noDoubleEquals": "error",
        "noDuplicateCase": "error",
        "noDuplicateClassMembers": "error",
        "noDuplicateObjectKeys": "error",
        "noDuplicateParameters": "error",
        "noEmptyBlockStatements": "warn",
        "noExplicitAny": "warn",
        "noExtraNonNullAssertion": "error",
        "noFallthroughSwitchClause": "error",
        "noFunctionAssign": "error",
        "noGlobalAssign": "error",
        "noImportAssign": "error",
        "noLabelVar": "error",
        "noMisleadingCharacterClass": "error",
        "noPrototypeBuiltins": "error",
        "noRedeclare": "error",
        "noSelfCompare": "error",
        "noShadowRestrictedNames": "error",
        "noUnsafeNegation": "error",
        "useDefaultSwitchClauseLast": "error",
        "useGetterReturn": "error",
        "useValidTypeof": "error"
      }
    }
  }
}

Critical suspicious patterns:

```
noExplicitAny
```
: Avoid any in TypeScript
```
noConsoleLog
```
: Remove console.log in production
```
noDebugger
```
: Remove debugger statements
```
noDoubleEquals
```
: Use === instead of ==
```
noDuplicateObjectKeys
```
: Catch duplicate keys

针对可疑代码模式的规则：

json

{
  "linter": {
    "rules": {
      "suspicious": {
        "recommended": true,
        "noArrayIndexKey": "warn",
        "noAssignInExpressions": "error",
        "noAsyncPromiseExecutor": "error",
        "noCatchAssign": "error",
        "noClassAssign": "error",
        "noCommentText": "error",
        "noCompareNegZero": "error",
        "noConsoleLog": "warn",
        "noControlCharactersInRegex": "error",
        "noDebugger": "error",
        "noDoubleEquals": "error",
        "noDuplicateCase": "error",
        "noDuplicateClassMembers": "error",
        "noDuplicateObjectKeys": "error",
        "noDuplicateParameters": "error",
        "noEmptyBlockStatements": "warn",
        "noExplicitAny": "warn",
        "noExtraNonNullAssertion": "error",
        "noFallthroughSwitchClause": "error",
        "noFunctionAssign": "error",
        "noGlobalAssign": "error",
        "noImportAssign": "error",
        "noLabelVar": "error",
        "noMisleadingCharacterClass": "error",
        "noPrototypeBuiltins": "error",
        "noRedeclare": "error",
        "noSelfCompare": "error",
        "noShadowRestrictedNames": "error",
        "noUnsafeNegation": "error",
        "useDefaultSwitchClauseLast": "error",
        "useGetterReturn": "error",
        "useValidTypeof": "error"
      }
    }
  }
}

关键可疑代码模式：

```
noExplicitAny
```
: 在TypeScript中避免使用any类型
```
noConsoleLog
```
: 在生产环境中移除console.log
```
noDebugger
```
: 移除debugger语句
```
noDoubleEquals
```
: 使用===替代==
```
noDuplicateObjectKeys
```
: 捕获重复的对象键

Rule Configuration Patterns

规则配置模式

Strict Configuration

严格配置

Maximum strictness for high-quality codebases:

json

{
  "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,
        "noExplicitAny": "error",
        "noConsoleLog": "error"
      }
    }
  }
}

针对高质量代码库的最高严格度配置：

json

{
  "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,
        "noExplicitAny": "error",
        "noConsoleLog": "error"
      }
    }
  }
}

Gradual Adoption

逐步适配

Start lenient and progressively tighten:

json

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

从宽松规则开始，逐步收紧：

json

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

Framework-Specific

框架专属配置

React configuration example:

json

{
  "linter": {
    "rules": {
      "recommended": true,
      "a11y": { "recommended": true },
      "correctness": {
        "recommended": true,
        "noChildrenProp": "error"
      },
      "security": {
        "noDangerouslySetInnerHtml": "error"
      },
      "suspicious": {
        "noArrayIndexKey": "error"
      }
    }
  }
}

React配置示例：

json

{
  "linter": {
    "rules": {
      "recommended": true,
      "a11y": { "recommended": true },
      "correctness": {
        "recommended": true,
        "noChildrenProp": "error"
      },
      "security": {
        "noDangerouslySetInnerHtml": "error"
      },
      "suspicious": {
        "noArrayIndexKey": "error"
      }
    }
  }
}

Ignoring Violations

忽略违规项

Inline Comments

行内注释

Suppress specific violations:

javascript

// biome-ignore lint/suspicious/noExplicitAny: Legacy code
function legacyFunction(data: any) {
  return data;
}

// biome-ignore lint/suspicious/noConsoleLog: Debug logging
console.log('Debug info');

// Multiple rules
// biome-ignore lint/suspicious/noExplicitAny lint/style/useConst: Migration
var config: any = {};

抑制特定违规：

javascript

// biome-ignore lint/suspicious/noExplicitAny: 遗留代码
function legacyFunction(data: any) {
  return data;
}

// biome-ignore lint/suspicious/noConsoleLog: 调试日志
console.log('Debug info');

// 多个规则
// biome-ignore lint/suspicious/noExplicitAny lint/style/useConst: 迁移中
var config: any = {};

File-Level Ignores

文件级忽略

Ignore entire file:

javascript

/* biome-ignore-file */

// Legacy file, skip all linting

忽略整个文件：

javascript

/* biome-ignore-file */

// 遗留文件，跳过所有代码检查

Configuration Ignores

配置文件忽略

Ignore patterns in biome.json:

json

{
  "files": {
    "ignore": [
      "**/generated/**",
      "**/*.config.js",
      "**/vendor/**"
    ]
  }
}

在biome.json中配置忽略模式：

json

{
  "files": {
    "ignore": [
      "**/generated/**",
      "**/*.config.js",
      "**/vendor/**"
    ]
  }
}

Best Practices

最佳实践

Enable Recommended Rules - Start with
```
"recommended": true
```
Progressive Enhancement - Add stricter rules gradually
Document Exceptions - Explain why rules are disabled
Use Inline Ignores Sparingly - Prefer fixing over ignoring
Security First - Never disable security rules
CI Enforcement - Use
```
biome ci
```
in pipelines
Pre-commit Hooks - Catch issues before commit
Team Agreement - Discuss rule changes with team
Regular Review - Periodically review disabled rules
Fix Warnings - Don't let warnings accumulate

启用推荐规则 - 从
```
"recommended": true
```
开始
逐步增强 - 逐步添加更严格的规则
记录例外情况 - 说明禁用规则的原因
谨慎使用行内忽略 - 优先修复而非忽略
安全优先 - 绝不禁用安全规则
CI强制执行 - 在流水线中使用
```
biome ci
```
提交前钩子 - 在提交前捕获问题
团队共识 - 与团队讨论规则变更
定期回顾 - 定期审查已禁用的规则
修复警告 - 不要让警告堆积

Common Pitfalls

常见误区

Ignoring Errors - Using biome-ignore instead of fixing
Disabling Security - Turning off security rules
No CI Check - Not enforcing in continuous integration
Too Lenient - Setting everything to "warn"
No Documentation - Not explaining disabled rules
Inconsistent Config - Different rules per package
Ignoring Warnings - Treating warnings as optional
Wrong Rule Names - Typos in rule configuration
Overly Strict - Blocking team productivity
No Migration Plan - Enabling all rules at once

忽略错误 - 使用biome-ignore而非修复问题
禁用安全规则 - 关闭安全相关规则
未配置CI检查 - 未在持续集成中强制执行
规则过于宽松 - 将所有规则设为"warn"
无文档说明 - 未解释禁用规则的原因
配置不一致 - 不同包使用不同规则
忽略警告 - 将警告视为可选项
规则名称错误 - 规则配置中出现拼写错误
规则过于严格 - 影响团队生产力
无迁移计划 - 一次性启用所有规则

Advanced Topics

进阶主题

Custom Rule Sets

自定义规则集

Create shared rule sets for organization:

json

{
  "extends": ["@company/biome-config"],
  "linter": {
    "rules": {
      "suspicious": {
        "noConsoleLog": "error"
      }
    }
  }
}

为组织创建共享规则集：

json

{
  "extends": ["@company/biome-config"],
  "linter": {
    "rules": {
      "suspicious": {
        "noConsoleLog": "error"
      }
    }
  }
}

Per-Directory Rules

按目录配置规则

Use overrides for different code areas:

json

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

使用覆盖配置针对不同代码区域设置规则：

json

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

Migration Strategy

迁移策略

Migrating from ESLint:

Install Biome:
```
npm install -D @biomejs/biome
```
Initialize:
```
npx biome init
```
Run Check:
```
npx biome check .
```
to see violations
Fix Automatically:
```
npx biome check --write .
```
Address Remaining: Fix issues that can't auto-fix
Tune Rules: Adjust rules based on team needs
Update CI: Replace ESLint with Biome
Remove ESLint: After validation period

从ESLint迁移至Biome：

安装Biome:
```
npm install -D @biomejs/biome
```
初始化:
```
npx biome init
```
执行检查:
```
npx biome check .
```
查看违规情况
自动修复:
```
npx biome check --write .
```
处理剩余问题: 修复无法自动修复的问题
调整规则: 根据团队需求调整规则
更新CI: 用Biome替换ESLint
移除ESLint: 验证完成后移除ESLint

Integration Patterns

集成方案

Package.json Scripts

Package.json脚本

json

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

json

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

Pre-commit Hook

提交前钩子

Using husky:

json

{
  "husky": {
    "hooks": {
      "pre-commit": "biome check --write --changed"
    }
  }
}

使用husky：

json

{
  "husky": {
    "hooks": {
      "pre-commit": "biome check --write --changed"
    }
  }
}

GitHub Actions

yaml

- name: Run Biome
  run: npx biome ci .

yaml

- name: Run Biome
  run: npx biome ci .

Troubleshooting

故障排查

False Positives

误报

If rule triggers incorrectly:

Verify rule is appropriate for your code
Check if bug in Biome (report upstream)
Use biome-ignore with explanation
Consider disabling rule if widespread

如果规则触发错误：

验证规则是否适用于你的代码
检查Biome是否存在bug（向上游反馈）
使用biome-ignore并添加说明
如果问题普遍，考虑禁用该规则

Performance Issues

性能问题

If linting is slow:

Update to latest Biome version
Use VCS integration
Ignore large generated directories
Check for file pattern issues

如果代码检查速度慢：

更新至最新版Biome
使用版本控制系统集成
忽略大型生成目录
检查文件模式是否存在问题

Rules Not Applied

规则未生效

Verify:

Linter is enabled in config
Rule category is enabled
Rule name is spelled correctly
No overrides disabling it
Files are not ignored

验证以下内容：

配置文件中已启用代码检查工具
规则分类已启用
规则名称拼写正确
没有覆盖配置禁用该规则
文件未被忽略

When to Use This Skill

适用场景

Setting up linting for new projects
Migrating from ESLint to Biome
Configuring rule sets for teams
Troubleshooting linting errors
Optimizing code quality checks
Establishing code standards
Training team on Biome linting
Integrating linting into CI/CD

为新项目搭建代码检查
从ESLint迁移至Biome
为团队配置规则集
排查代码检查错误
优化代码质量检测
建立代码标准
培训团队使用Biome代码检查
将代码检查集成至CI/CD流水线