格式化器

OpenCode 使用特定于语言的格式化器。

OpenCode 可以在文件被写入或编辑后，使用特定于语言的格式化器对其进行格式化。格式化器默认禁用；你需要在配置中启用它们，OpenCode 才会运行它们。

内置

OpenCode 自带若干面向流行语言和框架的内置格式化器。下面是格式化器列表、支持的文件扩展名，以及它所需要的命令或配置选项。

格式化器	扩展名	要求
air	.R	可用 `air` 命令
biome	.js, .jsx, .ts, .tsx, .html, .css, .md, .json, .yaml 等更多 (opens in a new tab)	`biome.json(c)` 配置文件
cargofmt	.rs	可用 `cargo fmt` 命令
clang-format	.c, .cpp, .h, .hpp, .ino 等更多 (opens in a new tab)	`.clang-format` 配置文件
cljfmt	.clj, .cljs, .cljc, .edn	可用 `cljfmt` 命令
dart	.dart	可用 `dart` 命令
dfmt	.d	可用 `dfmt` 命令
gleam	.gleam	可用 `gleam` 命令
gofmt	.go	可用 `gofmt` 命令
htmlbeautifier	.erb, .html.erb	可用 `htmlbeautifier` 命令
ktlint	.kt, .kts	可用 `ktlint` 命令
mix	.ex, .exs, .eex, .heex, .leex, .neex, .sface	可用 `mix` 命令
nixfmt	.nix	可用 `nixfmt` 命令
ocamlformat	.ml, .mli	可用 `ocamlformat` 命令和 `.ocamlformat` 配置文件
ormolu	.hs	可用 `ormolu` 命令
oxfmt（实验性）	.js, .jsx, .ts, .tsx	`package.json` 中有 `oxfmt` 依赖，以及一个实验性环境变量标志
pint	.php	`composer.json` 中有 `laravel/pint` 依赖
prettier	.js, .jsx, .ts, .tsx, .html, .css, .md, .json, .yaml 等更多 (opens in a new tab)	`package.json` 中有 `prettier` 依赖
rubocop	.rb, .rake, .gemspec, .ru	可用 `rubocop` 命令
ruff	.py, .pyi	可用 `ruff` 命令且带配置
rustfmt	.rs	可用 `rustfmt` 命令
shfmt	.sh, .bash	可用 `shfmt` 命令
standardrb	.rb, .rake, .gemspec, .ru	可用 `standardrb` 命令
terraform	.tf, .tfvars	可用 `terraform` 命令
uv	.py, .pyi	可用 `uv` 命令
zig	.zig, .zon	可用 `zig` 命令

当启用格式化器时，如果你的项目在 package.json 中有 prettier，OpenCode 会对匹配的文件使用 prettier。

工作原理

当 OpenCode 写入或编辑文件且格式化器已启用时，它会：

将文件扩展名与所有已启用的格式化器进行比对。
对该文件运行合适的格式化器命令。
应用格式化变更。

对于已启用的格式化器，这个过程在后台进行。

配置

你可以通过 OpenCode 配置中的 formatter 部分启用并自定义格式化器。

要启用所有内置格式化器，将 formatter 设为 true。

opencode.json

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

使用一个对象在保持内置格式化器启用的同时配置覆盖或自定义格式化器。

opencode.json

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

每个格式化器配置支持以下内容：

属性	类型	说明
`disabled`	boolean	将其设为 `true` 以禁用该格式化器
`command`	string[]	用于格式化的命令。对自定义格式化器为必需；对内置格式化器为可选。
`environment`	object	运行格式化器时设置的环境变量
`extensions`	string[]	该格式化器应处理的文件扩展名

让我们看几个示例。

禁用格式化器

如果省略 formatter，则所有格式化器都被禁用。要在另一个配置启用了格式化器之后禁用所有格式化器，将 formatter 设为 false：

opencode.json

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

要禁用特定的格式化器，将 disabled 设为 true：

opencode.json

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

自定义格式化器

你可以用 environment 或 extensions 等选项配置内置格式化器。要添加一个自定义格式化器，指定一个 command 和 extensions：

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"]
    }
  }
}

命令中的 $FILE 占位符会被替换为正在被格式化的文件的路径。

命令权限