---
url: https://eoht.net/notes/biome.md
description: 为项目安装和配置 Biome，以本站 Biome 2 配置为例说明文件范围、格式化、lint 与导入整理，并区分只读检查和写入修改的命令。
---

# 为项目添加 Biome {#add-biome-to-project}

## 1. 配置 Biome {#configure-biome-formatting}

Biome 可以统一代码格式、检查规则并执行导入整理等 assist 操作。它不检查提交信息，也不能代替项目构建和业务验证。下面先安装项目内依赖，再按项目实际范围配置。

### 安装 Biome {#install-biome}

::: code-group

```shell [pnpm]
pnpm add --save-dev @biomejs/biome
```

```shell [npm]
npm install --save-dev @biomejs/biome
```

```shell [yarn]
yarn add --dev @biomejs/biome
```

:::

### Biome 配置 {#biome-configuration}

以下通过 include 展示 **Eoht 本站的完整配置实例**，不是所有项目都适用的默认模板。核对时本站使用 Biome 2，配置 schema 为 `2.6.2`；安装版本应与使用的 schema 和字段相符，可先用 `pnpm exec biome --version` 查询。已有 Biome 配置时应逐项调整，不要整份覆盖。

```json
{
  "$schema": "https://biomejs.dev/schemas/2.6.2/schema.json",
  "vcs": {
    "enabled": true,
    "clientKind": "git",
    "useIgnoreFile": true
  },
  "files": {
    "ignoreUnknown": true,
    "includes": ["**", "!node_modules", "!.vitepress/cache", "!.vitepress/dist", "!dist", "!cache", "!temp", "!.temp"]
  },
  "formatter": {
    "enabled": true,
    "formatWithErrors": false,
    "indentStyle": "space",
    "indentWidth": 2,
    "lineEnding": "lf",
    "lineWidth": 120
  },
  "assist": {
    "enabled": true,
    "actions": {
      "source": {
        "organizeImports": "on"
      }
    }
  },
  "linter": {
    "enabled": true,
    "includes": ["**/*.ts", "**/*.mts", "**/*.json", "**/*.jsonc"],
    "rules": {
      "preset": "recommended",
      "suspicious": {
        "noTsIgnore": "error"
      }
    }
  },
  "javascript": {
    "formatter": {
      "quoteStyle": "single",
      "semicolons": "asNeeded",
      "trailingCommas": "none"
    }
  },
  "json": {
    "formatter": {
      "trailingCommas": "none"
    }
  },
  "css": {
    "formatter": {
      "quoteStyle": "single"
    }
  }
}

```

配置范围需要结合项目理解：

* `files.includes` 排除了依赖、构建输出和若干缓存目录；`vcs.useIgnoreFile` 同时使用 Git 忽略规则。
* `files.ignoreUnknown: true` 会忽略不支持的文件类型。检查成功不代表 Markdown 正文、命令或链接已经核验。
* `formatter` 负责缩进、换行等格式；`linter` 在本站只匹配 TypeScript、MTS、JSON 和 JSONC，并启用配置中的规则。
* `assist.actions.source.organizeImports` 启用导入整理。本站的两空格、单引号等风格是项目选择，其他仓库应遵循自己的约定。

新项目可使用 `pnpm exec biome init` 创建起点，再按 [官方配置说明](https://biomejs.dev/guides/configure-biome/) 调整；不要照搬本站目录排除项。

### 选择检查或写入命令 {#format-all-files-with-biome}

下表以 pnpm 为例，各命令只处理当前配置选中的受支持文件。执行写入命令前保留原有修改，完成后检查差异。

| 命令 | 作用 | 是否写文件 |
| --- | --- | --- |
| `pnpm exec biome check .` | 检查格式、lint 和已启用的 assist 操作 | 否 |
| `pnpm exec biome check --write .` | 应用格式化、导入整理和可安全自动修复的规则 | 是 |
| `pnpm exec biome format .` | 只检查格式 | 否 |
| `pnpm exec biome format --write .` | 只写入格式调整 | 是 |
| `pnpm exec biome lint .` | 只运行 lint 检查 | 否 |

`--write` 不保证所有诊断都能自动解决；剩余问题需要人工处理。命令含义见 [Biome CLI 文档](https://biomejs.dev/reference/cli/)。

下面是不同包管理器的**只读综合检查**入口：

::: code-group

```shell [pnpm]
pnpm exec biome check .
```

```shell [npm]
npx @biomejs/biome check .
```

```shell [yarn]
yarn biome check .
```

:::

确认需要自动修改时，再为 `check` 加上 `--write`。本站 `pnpm run format:check` 对应 `biome check .`，`pnpm run format` 对应 `biome check --write .`；其他项目是否有这两个脚本，应先查看自己的 `package.json`。