---
title: "配置格式化工具"
description: "OpenCode 使用特定語言的格式化工具。"
verifiedAt: "2026-05-09"
---

OpenCode 可以在寫入或編輯檔案後執行語言專用 formatter，讓生成程式碼貼近專案風格。但 formatter 預設停用，必須在配置裡啟用後才會執行。

> [!NOTE]
> **這一篇用 10 分鐘換什麼**：你會知道 formatter 什麼時候值得開、怎麼啟用內建 formatter、怎麼停用單個 formatter、怎麼配置自定義命令，以及為什麼格式化不能用來掩蓋邏輯改動。

## 先給結論：formatter 只做機械整理

Formatter 的職責是機械格式化，不是判斷程式碼是否正確。

```mermaid
flowchart LR
    Edit["OpenCode 寫入 / 編輯檔案"] --> Enabled{"formatter 已啟用?"}
    Enabled -->|否| Stop["不執行 formatter"]
    Enabled -->|是| Match["按副檔名匹配 formatter"]
    Match --> Command["執行 formatter command"]
    Command --> Apply["應用格式化結果"]
    Apply --> Review["檢查 diff / test / typecheck"]

    style Enabled fill:#dbeafe,stroke:#3b82f6,stroke-width:2px
    style Apply fill:#dcfce7,stroke:#22c55e
    style Review fill:#fee2e2,stroke:#ef4444
```

正確順序是先讓 agent 做最小邏輯改動，再執行測試或型別檢查，最後讓 formatter 收尾。不要一開始就全儲存庫格式化，否則真實邏輯 diff 會被淹沒。

> [!WARNING]
> **格式化透過不等於功能正確**：formatter 不知道業務意圖，也不會替你驗證執行時行為。它只能減少風格噪音。

## 1. 啟用 formatter

官方當前文件明確說明：如果省略 `formatter`，所有 formatter 都是停用狀態。

要啟用所有內建 formatter：

```json title="opencode.json"
{
  "$schema": "https://opencode.ai/config.json",
  "formatter": true
}
```

要保留内置 formatter，同时覆盖某些配置或添加自定义 formatter，可以写成对象：

```json title="opencode.json"
{
  "$schema": "https://opencode.ai/config.json",
  "formatter": {}
}
```

如果项目 `package.json` 里有 `prettier` 依赖，并且 formatter 已启用，OpenCode 会对匹配文件使用 `prettier`。

## 2. 内置 formatter 怎么判断

OpenCode 内置了多种 formatter，但前提不一样。不要只看扩展名，还要看项目配置、依赖和本机命令。

| 类型 | 代表 formatter | 前提 |
| --- | --- | --- |
| JS / TS / Web | `prettier`、`biome`、`oxfmt` | `prettier` 依赖、`biome.json(c)`、`oxfmt` 依赖和实验变量 |
| 系统命令 | `gofmt`、`rustfmt`、`shfmt`、`terraform`、`zig`、`dart`、`gleam`、`nixfmt` | 对应命令必须可用 |
| 语言生态工具 | `cargofmt`、`mix`、`rubocop`、`standardrb`、`pint`、`ruff`、`uv` | 对应包管理器、项目依赖或配置存在 |
| 配置驱动 | `clang-format`、`ocamlformat`、`ruff`、`biome` | 项目里有对应配置文件 |

这张表不是完整支持矩阵，而是判断方法。完整扩展名和工具列表以官方 Formatters 页面为准。

## 3. 配置项

每个 formatter configuration 支持：

| 字段 | 作用 |
| --- | --- |
| `disabled` | 设置为 `true` 禁用该 formatter |
| `command` | 格式化命令；自定义 formatter 必填，内置 formatter 可选 |
| `environment` | 运行 formatter 时注入环境变量 |
| `extensions` | 由该 formatter 处理的文件扩展名 |

自定义命令里可以使用 `$FILE` 占位符，OpenCode 会把它替换成待格式化文件路径。

## 4. 禁用 formatter

如果上层配置已经启用了 formatter，但当前项目不想运行，可以显式关闭：

```json title="opencode.json"
{
  "$schema": "https://opencode.ai/config.json",
  "formatter": false
}
```

只禁用某个 formatter：

```json title="opencode.json"
{
  "$schema": "https://opencode.ai/config.json",
  "formatter": {
    "prettier": {
      "disabled": true
    }
  }
}
```

适合禁用的场景：formatter 版本和项目不一致、monorepo 子包规则冲突、生成代码不应该格式化、当前任务只允许最小 diff、或格式化工具会修改大量无关文件。

## 5. 自定义 formatter

可以覆盖内置 formatter，也可以添加项目专用 formatter。

```json title="opencode.json"
{
  "$schema": "https://opencode.ai/config.json",
  "formatter": {
    "prettier": {
      "command": ["npx", "prettier", "--write", "$FILE"],
      "environment": {
        "NODE_ENV": "development"
      },
      "extensions": [".js", ".ts", ".jsx", ".tsx"]
    },
    "custom-markdown-formatter": {
      "command": ["deno", "fmt", "$FILE"],
      "extensions": [".md"]
    }
  }
}
```

自定义 formatter 进入项目配置前，先在终端里单独验证：

```bash
npx prettier --write path/to/file.ts
deno fmt path/to/file.md
```

> [!IMPORTANT]
> **自定义 formatter 必须是确定性的**：同一个文件连续运行两次，第二次不应该再产生 diff。否则 OpenCode 会把格式化噪音带进每轮修改。

## 6. 推荐改动流程

对真实项目，建议按这个顺序执行：

```text
1. 任務前檢視 git status
2. 限定本輪可修改檔案
3. 讓 OpenCode 完成最小邏輯改動
4. 跑 test / typecheck / lint
5. 執行 formatter 或讓啟用的 formatter 收尾
6. 檢查 diff 是否只在預期範圍
```

如果 formatter 造成大範圍 diff，先停下來，不要繼續疊加新邏輯。把格式化 diff 單獨處理，或者暫時停用相關 formatter。

## 7. 驗收清單

啟用 formatter 前後，檢查這幾項：

- `formatter` 明確啟用或停用，不依賴猜測。
- 專案確實有對應 formatter 依賴、命令或配置檔案。
- 自定義 `command` 能獨立執行。
- `$FILE` 佔位符位置正確。
- formatter 不會觸碰無關語言或生成目錄。
- 執行後 diff 沒有淹沒業務改動。

## 接下來去哪

<Cards>
  <Card title="LSP 伺服器" description="LSP 提供診斷訊號，formatter 做機械整理，兩者職責不同。" href="/zh-Hant/docs/opencode/official/04-tools-mcp/lsp" />
  <Card title="工具總覽" description="理解 formatter 在內建工具、custom tools、MCP 之間的位置。" href="/zh-Hant/docs/opencode/official/04-tools-mcp/tools" />
  <Card title="配置" description="確認 `formatter` 應該放在全域性配置還是專案配置。" href="/zh-Hant/docs/opencode/official/01-customization/config" />
  <Card title="許可權" description="格式化通常伴隨檔案寫入，仍要理解 edit/bash 等許可權邊界。" href="/zh-Hant/docs/opencode/official/05-security/permissions" />
</Cards>

## 官方資料

- OpenCode Formatters：[https://opencode.ai/docs/formatters](https://opencode.ai/docs/formatters)
- OpenCode Configuration：[https://opencode.ai/docs/config](https://opencode.ai/docs/config)
- OpenCode Tools：[https://opencode.ai/docs/tools](https://opencode.ai/docs/tools)
- OpenCode Permissions：[https://opencode.ai/docs/permissions](https://opencode.ai/docs/permissions)
