OpenCode 格式化器（Formatters）完全指南：让 AI 编程助手自动保持代码风格统一

OpenCode 格式化器（Formatters）完全指南：让 AI 编程助手自动保持代码风格统一

在团队协作中，代码风格统一是一个老生常谈却不易解决的问题。不同的开发者有不同的编码习惯，手动格式化代码既耗时又容易遗漏。OpenCode 的格式化器（Formatters）功能，正是为解决这个问题而生的——它能在 AI 编程助手每次写入或编辑文件后，自动运行对应的格式化工具，确保输出的代码始终符合项目规范。

本文将从基础配置到高级自定义，全面讲解 OpenCode Formatters 的使用方法。

什么是 OpenCode 格式化器？

OpenCode Formatters 是内置的代码格式化系统。当 OpenCode 生成或修改代码后，格式化器会在后台自动检测文件类型，找到对应的格式化工具并执行，最终将格式化后的结果写回文件。整个过程完全自动化，对用户透明。

它与 LSP（语言服务器协议）的区别在于：LSP 提供实时的代码分析、补全和诊断，而 Formatters 专注于输出后格式化，确保最终写入文件的代码风格正确。

内置格式化器一览

OpenCode 为 20 多种主流语言和框架提供了内置格式化器，开箱即用。以下是完整列表：

| 格式化器 | 支持扩展名 | 要求 |
|---------|-----------|------|
| air | .R | air 命令可用 |
| biome | .js, .jsx, .ts, .tsx, .html, .css, .md 等 | biome.json(c) 配置文件 |
| cargofmt | .rs | cargo fmt 命令可用 |
| clang-format | .c, .cpp, .h, .hpp 等 | .clang-format 配置文件 |
| dart | .dart | dart 命令可用 |
| gofmt | .go | gofmt 命令可用 |
| ktlint | .kt, .kts | ktlint 命令可用 |
| mix | .ex, .exs, .eex, .heex | mix 命令可用 |
| pint | .php | laravel/pint 在 composer.json 中 |
| prettier | .js, .jsx, .ts, .tsx, .html, .css, .md 等 | prettier 在 package.json 中 |
| rubocop | .rb, .rake | rubocop 命令可用 |
| ruff | .py, .pyi | ruff 命令可用且有配置 |
| shfmt | .sh, .bash | shfmt 命令可用 |
| terraform | .tf, .tfvars | terraform 命令可用 |

当启用格式化器时，如果项目中有 prettier 依赖，OpenCode 会优先使用 Prettier 处理匹配的文件。

启用和配置格式化器

格式化器默认是禁用的，需要在 opencode.json 中手动开启。

启用所有内置格式化器

最简单的配置是将 formatter 设为 true：

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

这行配置会启用所有已安装（即命令可用）的内置格式化器。

使用对象语法精细控制

如果你需要保持内置格式化器启用，同时添加自定义配置，可以使用对象语法：

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

空的 {} 表示启用所有内置格式化器，后续可以在其中添加具体的配置项。

禁用特定格式化器

有时候你可能不想使用某个特定格式化器，例如团队统一使用 ESLint 而不是 Prettier。可以单独禁用它：

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

如果要完全禁用所有格式化器，直接设为 false：

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

自定义格式化器

OpenCode 的强大之处在于它的可扩展性。当内置格式化器不满足需求时，你可以创建自定义格式化器。

覆盖内置格式化器

假设你想让 Prettier 在某些特定环境下运行，可以覆盖默认配置：

{
  "$schema": "https://opencode.ai/config.json",
  "formatter": {
    "prettier": {
      "command": ["npx", "prettier", "--write", "$FILE"],
      "environment": {
        "NODE_ENV": "development"
      },
      "extensions": [".js", ".ts", ".jsx", ".tsx"]
    }
  }
}

添加全新格式化器

如果你想用 Deno 来格式化 Markdown 文件，可以添加一个自定义条目：

{
  "$schema": "https://opencode.ai/config.json",
  "formatter": {
    "custom-markdown-formatter": {
      "command": ["deno", "fmt", "$FILE"],
      "extensions": [".md"]
    }
  }
}

这里的 $FILE 占位符会被自动替换为当前正在格式化的文件路径。

格式化器的工作原理

了解内部机制有助于更好地配置和使用。当 OpenCode 写入或编辑文件后，格式化流程如下：

文件匹配：检测写入文件的扩展名，与所有启用的格式化器进行匹配

命令执行：找到匹配的格式化器后，在后台执行对应的格式化命令

应用更改：将格式化后的内容写回文件

整个过程在后台异步完成，不会阻塞你的工作流。

实战示例

场景一：Laravel 项目

对于 Laravel 项目，OpenCode 会自动检测 laravel/pint 依赖并格式化 PHP 代码：

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

如果你的项目同时包含 Vue/JS 文件，建议添加 Prettier 依赖到 package.json，OpenCode 会自动识别并使用。

场景二：Python 项目

Python 项目推荐使用 Ruff，它速度极快且功能全面：

{
  "$schema": "https://opencode.ai/config.json",
  "formatter": {
    "ruff": {
      "command": ["ruff", "format", "$FILE"],
      "extensions": [".py", ".pyi"]
    }
  }
}

场景三：Go 项目

Go 语言有官方推荐的 gofmt，几乎不需要额外配置：

{
  "$schema": "https://opencode.ai/config.json",
  "formatter": {
    "gofmt": {
      "extensions": [".go"]
    }
  }
}

gofmt 命令默认在 Go 环境中可用，OpenCode 会自动调用。

与编辑器格式化工具的协作

需要注意的是，OpenCode 的格式化器只对 AI 生成的代码生效，并不会格式化你手动编辑的文件。这意味着你可以同时使用 VS Code 的 "Format on Save" 功能和 OpenCode 的格式化器，两者互不干扰。

如果你在 opencode.json 中启用了格式化器，建议在 AGENTS.md 中也注明团队采用的代码风格规范，让 AI 在生成代码时就尽可能符合预期，格式化器再做二次保障。

最佳实践

从简单开始：先用 "formatter": true 体验，再根据需要逐步自定义

统一工具链：团队应在项目中锁定格式化器版本，确保 AI 生成和人工修改风格一致

利用 $FILE 占位符：自定义命令时善用这个变量，避免硬编码

结合 Rules：在 AGENTS.md 中说明代码风格要求，从源头减少格式化修正

持续集成：配合 CI 中的格式化检查，确保所有提交都符合规范

总结

OpenCode 的格式化器功能看似简单，却是保证 AI 生成代码质量的重要一环。它内置了 20 多种主流语言的格式化工具，支持完全自定义扩展，让团队无需额外操作就能维持统一的代码风格。

无论你是使用 Prettier 的前端团队、用 Pint 的 Laravel 开发者，还是用 Ruff 的 Python 工程师，OpenCode 的格式化器都能完美适配你的工作流。在配置文件中启用它，让 AI 编程助手不仅写得出代码，更写得出一手好代码。