OpenCode 格式化工具
OpenCode 会在每次写入或编辑文件后，自动使用对应语言的格式化工具对其进行格式化，确保生成的代码始终符合你项目的代码风格。整个过程在后台静默完成，无需任何手动操作。
工作原理
当 OpenCode 写入或编辑文件时，会按以下步骤自动执行格式化：
- 检测被写入或编辑的文件扩展名（如
.ts、.py、.go等） - 将扩展名与所有已启用的格式化工具进行匹配
- 对该文件运行匹配到的格式化命令
- 自动将格式化结果写回文件
例如，如果你的项目 package.json 中包含 prettier 依赖，OpenCode 就会自动检测到并在每次编辑 .js、.ts、.css 等文件后调用 prettier 进行格式化，无需任何额外配置。
内置格式化工具
OpenCode 内置了覆盖主流语言和框架的格式化工具支持，分为两类：
- 命令可用即启用：只需在系统中安装对应命令，OpenCode 会自动检测并使用
- 需要项目配置文件或依赖：需要在项目中包含特定的配置文件或依赖包
| 格式化工具 | 支持的文件扩展名 | 启用要求 |
|---|---|---|
air | .R | air 命令可用 |
biome | .js .jsx .ts .tsx .html .css .md .json .yaml 及更多 | 项目中存在 biome.json 或 biome.jsonc 配置文件 |
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 命令可用 |
当多个格式化工具支持同一扩展名时（例如
.rs同时被cargofmt和rustfmt支持，.rb同时被rubocop和standardrb支持），OpenCode 会根据项目中已安装的工具自动选择。如需明确指定，可通过下方配置禁用不需要的格式化工具。
配置文件结构
格式化工具的自定义配置写在 opencode.json 的 formatter 字段下，键名为格式化工具名称（与内置表格中的名称一致），值为该工具的配置对象：
实例
{
"$schema": "https://opencode.ai/config.json",
"formatter": {
// 格式化工具名称: 配置对象
"prettier": {
// 在此填写 prettier 的配置项
}
}
}每个格式化工具支持以下配置项：
| 配置项 | 类型 | 说明 |
|---|---|---|
disabled | boolean | 设为 true 可禁用该格式化工具，其余配置项将被忽略 |
command | string[] | 执行格式化的命令数组。命令中可使用 $FILE 占位符，运行时会被替换为待格式化文件的完整路径 |
environment | object | 运行格式化工具时注入的环境变量，键值对形式 |
extensions | string[] | 该格式化工具处理的文件扩展名列表（包含 .，如 ".ts"） |
禁用格式化工具
1、禁用所有格式化工具
如果你不希望 OpenCode 对任何文件进行自动格式化，可以将 formatter 直接设为 false：
实例
{
"$schema": "https://opencode.ai/config.json",
"formatter": false // 全局禁用所有格式化工具，文件写入后不会进行任何格式化
}2、禁用特定格式化工具
如果只需要禁用某一个格式化工具，在对应工具的配置对象中将 disabled 设为 true，其他格式化工具不受影响：
实例
{
"$schema": "https://opencode.ai/config.json",
"formatter": {
"prettier": {
"disabled": true // 仅禁用 prettier，其他格式化工具（如 ruff、gofmt）仍正常工作
}
}
}自定义格式化工具
通过 command、environment 和 extensions 配置项，可以覆盖内置格式化工具的默认行为，或添加 OpenCode 尚未内置的格式化工具。
1、覆盖内置格式化工具的命令
例如，为 prettier 指定特定的参数，并限制它只处理特定扩展名：
实例
{
"$schema": "https://opencode.ai/config.json",
"formatter": {
"prettier": {
"command": ["npx", "prettier", "--write", "$FILE"],
// command 数组中的 $FILE 是占位符，运行时会被替换为待格式化文件的完整路径
// 例如实际执行：npx prettier --write /your/project/src/index.ts
"environment": {
"NODE_ENV": "development" // 运行 prettier 时注入的环境变量
},
"extensions": [".js", ".ts", ".jsx", ".tsx"]
// 覆盖默认扩展名：只对这四种文件运行 prettier，不处理 .html、.css 等
}
}
}2、添加自定义格式化工具
如果你使用的格式化工具不在内置列表中，可以通过指定任意名称来添加。只需提供启动命令和需要处理的文件扩展名即可：
实例
{
"$schema": "https://opencode.ai/config.json",
"formatter": {
"custom-markdown-formatter": { // 自定义名称（任意命名，不与内置工具冲突即可）
"command": ["deno", "fmt", "$FILE"],
// 使用 deno fmt 格式化文件，$FILE 会被替换为实际文件路径
"extensions": [".md"] // 只对 .md 文件运行此格式化工具
}
}
}3、同时配置多个格式化工具
实例
{
"$schema": "https://opencode.ai/config.json",
"formatter": {
"prettier": {
"command": ["npx", "prettier", "--write", "$FILE"],
"environment": {
"NODE_ENV": "development"
},
"extensions": [".js", ".ts", ".jsx", ".tsx"]
},
"ruff": {
"disabled": true // 项目中不使用 ruff，将其禁用
},
"custom-markdown-formatter": {
"command": ["deno", "fmt", "$FILE"],
"extensions": [".md"]
}
}
}AI 思考中...