OpenCode 格式化工具

OpenCode 内置自动代码格式化机制，在文件被创建或修改后，会自动调用对应语言的格式化工具进行处理，确保代码风格统一、规范一致。

OpenCode 的格式化系统本质是自动化代码风格治理机制。

它将 写代码 → 格式化 这一流程内置化，使 AI 生成代码能够直接符合团队规范，避免额外的 lint / format 成本，从而实现真正的无缝开发体验。

一、核心机制

当 OpenCode 对代码进行写入或编辑时，会自动执行以下流程：

  • 识别文件扩展名（如 .js、.py、.go 等）
  • 匹配对应的格式化工具
  • 执行格式化命令
  • 将格式化结果写回文件

整个过程无需人工干预，在后台自动完成。

二、内置格式化工具

OpenCode 已内置主流语言的格式化工具支持，以下为核心映射关系：

工具 支持扩展名 使用条件
prettier .js, .ts, .html, .css, .json, .md 等 package.json 中存在 prettier
biome .js, .ts, .json, .html 等 存在 biome.json(c)
gofmt .go gofmt 命令可用
rustfmt .rs rustfmt 可用
ruff .py ruff 命令 + 配置文件
clang-format .c, .cpp, .h 等 .clang-format 配置存在
shfmt .sh, .bash shfmt 命令可用
terraform .tf, .tfvars terraform 命令可用
rubocop .rb rubocop 命令可用
dart .dart dart 命令可用
zig .zig zig 命令可用

例如：

  • 项目中存在 prettier → 自动使用 Prettier
  • Go 项目 → 自动调用 gofmt
  • Rust 项目 → 自动执行 rustfmt

三、配置入口

通过 opencode.json 中的 formatter 字段进行控制： 

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

四、禁用格式化

1. 禁用全部格式化

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

2. 禁用单个工具

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

适用于：

  • 已有 CI/CD 格式化流程
  • 不希望 AI 自动改动代码格式

五、自定义格式化工具

你可以完全覆盖或扩展默认格式化行为。 

{
  "$schema": "https://opencode.ai/config.json",
  "formatter": {
    "prettier": {
      "command": ["npx", "prettier", "--write", "$FILE"],
      "environment": {
        "NODE_ENV": "development"
      },
      "extensions": [".js", ".ts", ".jsx", ".tsx"]
    }
  }
}

关键字段说明：

字段 说明
command 执行命令（数组形式）
environment 运行时环境变量
extensions 匹配的文件类型
disabled 是否禁用

六、$FILE 占位符

在 command 中使用 $FILE 表示当前处理的文件路径： 

["prettier", "--write", "$FILE"]

执行时会自动替换为： 

prettier --write src/index.ts

七、自定义扩展示例

为 Markdown 添加自定义格式化工具：

{
  "formatter": {
    "custom-md": {
      "command": ["deno", "fmt", "$FILE"],
      "extensions": [".md"]
    }
  }
}

适用于：

  • 团队统一 Markdown 风格
  • 接入内部格式化工具

八、执行优先级与匹配逻辑

OpenCode 在运行时会：

  1. 遍历所有 formatter 配置
  2. 匹配文件扩展名
  3. 按配置执行命令
  4. 应用结果

如果多个 formatter 匹配同一扩展名：

  • 通常按定义顺序执行
  • 建议避免重复配置同一扩展名

九、最佳实践

  • 优先使用项目已有格式化工具（如 Prettier / Ruff）
  • 确保配置文件（.prettierrc、.clang-format 等）存在
  • 避免多个工具同时处理同一文件类型
  • 在 CI 中保持一致的格式化策略
  • 必要时关闭自动格式化避免冲突