Formatter
OpenCode 可以在 write、edit 或 patch 工具修改文件后,对其执行格式化操作。默认情况下,格式化功能是关闭的,因此需要在配置中启用:
opencode.jsonc{
"$schema": "https://opencode.ai/config.json",
"formatter": true,
}
将 formatter 设为 true 即可启用所有内置 Formatter。只有当可执行文件及项目特定依赖均可用时,OpenCode 才会运行对应的内置 Formatter。
opencode.jsonc{
"$schema": "https://opencode.ai/config.json",
"formatter": true,
}
若使用对象形式,同样会启用内置 Formatter,并允许你覆盖默认配置或添加自定义 Formatter。使用空对象可以保留继承的 Formatter 设置,而使用 true 则会将设置重置为内置默认值。
opencode.jsonc{
"$schema": "https://opencode.ai/config.json",
"formatter": {},
}
OpenCode 内置了以下 Formatter 定义。大多数要求对应的命令已可用;部分定义具有额外的检测规则,下表列出了这些规则。
| Formatter | 扩展名 | 要求 |
| gofmt | .go | gofmt 命令 |
| mix | .ex, .exs, .eex, .heex, .leex, .neex, .sface | mix 命令 |
| oxfmt | .js, .jsx, .mjs, .cjs, .ts, .tsx, .mts, .cts | package.json 中声明 oxfmt 依赖 |
| prettier | .js, .jsx, .mjs, .cjs, .ts, .tsx, .mts, .cts, .html, .htm, .css, .scss, .sass, .less, .vue, .svelte, .json, .jsonc, .yaml, .yml, .toml, .xml, .md, .mdx, .graphql, .gql | package.json 中声明 prettier 依赖 |
| biome | 同上述 prettier 的扩展名 | 存在 biome.json 或 biome.jsonc,且已安装 @biomejs/biome 二进制文件 |
| zig | .zig, .zon | zig 命令 |
| clang-format | .c, .cc, .cpp, .cxx, .c++, .h, .hh, .hpp, .hxx, .h++, .ino, .C, .H | clang-format 命令,且存在 .clang-format 文件 |
| ktlint | .kt, .kts | ktlint 命令 |
| ruff | .py, .pyi | ruff 命令,且存在 Ruff 配置文件或依赖声明 |
| air | .R | 识别为 R 语言 Formatter 的 air 命令 |
| uv | .py, .pyi | 支持 uv format 的 uv 命令 |
| rubocop | .rb, .rake, .gemspec, .ru | rubocop 命令 |
| standardrb | .rb, .rake, .gemspec, .ru | standardrb 命令 |
| htmlbeautifier | .erb | htmlbeautifier 命令 |
| dart | .dart | dart 命令 |
| ocamlformat | .ml, .mli | ocamlformat 命令,且存在 .ocamlformat 文件 |
| raform | .tf, .tfvars | terraform 命令 |
| latexindent | .tex | latexindent 命令 |
| gleam | .gleam | gleam 命令 |
| shfmt | .sh, .bash | shfmt 命令 |
| nixfmt | .nix | nixfmt 命令 |
| rustfmt | .rs | rustfmt 命令 |
| pint | .php | composer.json 中声明 laravel/pint |
| ormolu | .hs | ormolu 命令 |
| cljfmt | .clj, .cljs, .cljc, .edn | cljfmt 命令 |
| dfmt | .d | dfmt 命令 |
例如,启用内置 Formatter 后,OpenCode 可以针对匹配的文件发现并运行项目本地的 Prettier 依赖:
opencode.jsonc{
"formatter": true,
}
添加具名条目可覆盖内置 Formatter 或定义自定义 Formatter。自定义 Formatter 必须同时提供 command 和 extensions 才能运行。
opencode.jsonc{
"$schema": "https://opencode.ai/config.json",
"formatter": {
"prettier": {
"environment": {
"NODE_ENV": "development",
},
"extensions": [".js", ".ts"],
},
"deno-markdown": {
"command": ["deno", "fmt", "$FILE"],
"extensions": [".md"],
},
},
}
| 字段 | 类型 | 行为 |
| disabled | boolean | 设为 true 时移除该具名 Formatter |
| command | string[] | 替换内置命令,或定义自定义命令 |
| environment | Record<string, string> | 追加环境变量,同时保留父级环境变量 |
| extensions | string[] | 替换内置扩展名列表,或定义自定义列表。需包含前导点 |
所有字段均为可选。内置条目在省略某字段时继承其值;而新条目若缺少 command 或 extensions 则无法运行。
opencode.jsonc{
"formatter": {
"prettier": {
"extensions": [".md", ".mdx"],
},
},
}
command 是一个参数数组,而非 shell 命令字符串。OpenCode 会用文件的绝对路径替换 $FILE,并在当前项目目录下执行该命令。
opencode.jsonc{
"formatter": {
"custom": {
"command": ["custom-fmt", "--write", "$FILE"],
"extensions": [".custom"],
},
},
}
OpenCode 会将文件的最终扩展名与 extensions 进行比对。匹配区分大小写,且像 .part.md 这样的复合条目不会匹配 notes.part.md,因为该文件的最终扩展名是 .md。
opencode.jsonc{
"formatter": {
"markdown": {
"command": ["deno", "fmt", "$FILE"],
"extensions": [".md"],
},
},
}
当多个 Formatter 匹配时,OpenCode 按注册顺序依次尝试,并在首个命令执行成功后停止。内置 Formatter 保持其固有的内置顺序,自定义条目则遵循对象中的声明顺序。若某个命令执行失败,OpenCode 会记录失败日志并尝试下一个匹配项。
opencode.jsonc{
"formatter": {
"preferred": {
"command": ["preferred-fmt", "$FILE"],
"extensions": [".foo"],
},
"fallback": {
"command": ["fallback-fmt", "$FILE"],
"extensions": [".foo"],
},
},
}
若任何配置文件均未设置 formatter,则格式化功能处于关闭状态。若要禁用由低优先级文件启用的格式化,需将其设为 false。
opencode.jsonc{
"$schema": "https://opencode.ai/config.json",
"formatter": false,
}
若要在保留其他内置 Formatter 的同时禁用某一项,请将其具名条目标记为 disabled。
opencode.jsonc{
"formatter": {
"prettier": {
"disabled": true,
},
},
}