进阶 opencode.ai 2026-11-11 16:13:22 · 14 阅读

第18章 第 18 章:格式化器配置

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.gogofmt 命令
mix.ex, .exs, .eex, .heex, .leex, .neex, .sfacemix 命令
oxfmt.js, .jsx, .mjs, .cjs, .ts, .tsx, .mts, .ctspackage.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, .gqlpackage.json 中声明 prettier 依赖
biome同上述 prettier 的扩展名存在 biome.json 或 biome.jsonc,且已安装 @biomejs/biome 二进制文件
zig.zig, .zonzig 命令
clang-format.c, .cc, .cpp, .cxx, .c++, .h, .hh, .hpp, .hxx, .h++, .ino, .C, .Hclang-format 命令,且存在 .clang-format 文件
ktlint.kt, .ktsktlint 命令
ruff.py, .pyiruff 命令,且存在 Ruff 配置文件或依赖声明
air.R识别为 R 语言 Formatter 的 air 命令
uv.py, .pyi支持 uv format 的 uv 命令
rubocop.rb, .rake, .gemspec, .rurubocop 命令
standardrb.rb, .rake, .gemspec, .rustandardrb 命令
htmlbeautifier.erbhtmlbeautifier 命令
dart.dartdart 命令
ocamlformat.ml, .mliocamlformat 命令,且存在 .ocamlformat 文件
raform.tf, .tfvarsterraform 命令
latexindent.texlatexindent 命令
gleam.gleamgleam 命令
shfmt.sh, .bashshfmt 命令
nixfmt.nixnixfmt 命令
rustfmt.rsrustfmt 命令
pint.phpcomposer.json 中声明 laravel/pint
ormolu.hsormolu 命令
cljfmt.clj, .cljs, .cljc, .edncljfmt 命令
dfmt.ddfmt 命令
例如,启用内置 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"], }, }, }
字段类型行为
disabledboolean设为 true 时移除该具名 Formatter
commandstring[]替换内置命令,或定义自定义命令
environmentRecord<string, string>追加环境变量,同时保留父级环境变量
extensionsstring[]替换内置扩展名列表,或定义自定义列表。需包含前导点
所有字段均为可选。内置条目在省略某字段时继承其值;而新条目若缺少 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, }, }, }

评论 (0)