OpenCode 格式化工具

OpenCode 会在每次写入或编辑文件后，自动使用对应语言的格式化工具对其进行格式化，确保生成的代码始终符合你项目的代码风格。整个过程在后台静默完成，无需任何手动操作。

工作原理

当 OpenCode 写入或编辑文件时，会按以下步骤自动执行格式化：

  1. 检测被写入或编辑的文件扩展名（如 .ts、.py、.go 等）
  2. 将扩展名与所有已启用的格式化工具进行匹配
  3. 对该文件运行匹配到的格式化命令
  4. 自动将格式化结果写回文件

例如，如果你的项目 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"]
    }
  }
}