格式化器

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

内置格式化器

OpenCode 为流行的语言和框架内置了多种格式化器。以下是格式化器列表、支持的文件扩展名及其所需的命令或配置选项。

格式化器	扩展名	要求
air	.R	`air` 命令可用
biome	.js, .jsx, .ts, .tsx, .html, .css, .md, .json, .yaml 等	需要 `biome.json(c)` 配置文件
cargofmt	.rs	`cargo fmt` 命令可用
clang-format	.c, .cpp, .h, .hpp, .ino 等	需要 `.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 等	需要 `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。

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

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

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

每个格式化器配置支持以下属性：

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

以下是一些示例。

禁用格式化器

如果省略 formatter，所有格式化器都会被禁用。在其他配置启用后想禁用所有格式化器，请将 formatter 设置为 false：

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

要禁用某个特定格式化器，请将 disabled 设置为 true：

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

自定义格式化器

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

{
  "$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 占位符会被替换为正在格式化的文件路径。