配置格式化工具

OpenCode 可以在寫入或編輯檔案後執行語言專用 formatter，讓生成程式碼貼近專案風格。但 formatter 預設停用，必須在配置裡啟用後才會執行。

先給結論：formatter 只做機械整理

Formatter 的職責是機械格式化，不是判斷程式碼是否正確。

flowchart LR
    Edit["OpenCode 寫入 / 編輯檔案"] --> Enabled{"formatter 已啟用?"}
    Enabled -->|否| Stop["不執行 formatter"]
    Enabled -->|是| Match["按副檔名匹配 formatter"]
    Match --> Command["執行 formatter command"]
    Command --> Apply["應用格式化結果"]
    Apply --> Review["檢查 diff / test / typecheck"]

    style Enabled fill:#dbeafe,stroke:#3b82f6,stroke-width:2px
    style Apply fill:#dcfce7,stroke:#22c55e
    style Review fill:#fee2e2,stroke:#ef4444

正確順序是先讓 agent 做最小邏輯改動，再執行測試或型別檢查，最後讓 formatter 收尾。不要一開始就全儲存庫格式化，否則真實邏輯 diff 會被淹沒。

1. 啟用 formatter

官方當前文件明確說明：如果省略 formatter，所有 formatter 都是停用狀態。

要啟用所有內建 formatter：

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

要保留内置 formatter，同时覆盖某些配置或添加自定义 formatter，可以写成对象：

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

如果项目 package.json 里有 prettier 依赖，并且 formatter 已启用，OpenCode 会对匹配文件使用 prettier。

2. 内置 formatter 怎么判断

OpenCode 内置了多种 formatter，但前提不一样。不要只看扩展名，还要看项目配置、依赖和本机命令。

这张表不是完整支持矩阵，而是判断方法。完整扩展名和工具列表以官方 Formatters 页面为准。

3. 配置项

每个 formatter configuration 支持：

自定义命令里可以使用 $FILE 占位符，OpenCode 会把它替换成待格式化文件路径。

4. 禁用 formatter

如果上层配置已经启用了 formatter，但当前项目不想运行，可以显式关闭：

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

只禁用某个 formatter：

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

适合禁用的场景：formatter 版本和项目不一致、monorepo 子包规则冲突、生成代码不应该格式化、当前任务只允许最小 diff、或格式化工具会修改大量无关文件。

5. 自定义 formatter

可以覆盖内置 formatter，也可以添加项目专用 formatter。

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

自定义 formatter 进入项目配置前，先在终端里单独验证：

npx prettier --write path/to/file.ts
deno fmt path/to/file.md

6. 推荐改动流程

对真实项目，建议按这个顺序执行：

1. 任務前檢視 git status
2. 限定本輪可修改檔案
3. 讓 OpenCode 完成最小邏輯改動
4. 跑 test / typecheck / lint
5. 執行 formatter 或讓啟用的 formatter 收尾
6. 檢查 diff 是否只在預期範圍

如果 formatter 造成大範圍 diff，先停下來，不要繼續疊加新邏輯。把格式化 diff 單獨處理，或者暫時停用相關 formatter。

7. 驗收清單

啟用 formatter 前後，檢查這幾項：

• formatter 明確啟用或停用，不依賴猜測。
• 專案確實有對應 formatter 依賴、命令或配置檔案。
• 自定義 command 能獨立執行。
• $FILE 佔位符位置正確。
• formatter 不會觸碰無關語言或生成目錄。
• 執行後 diff 沒有淹沒業務改動。

接下來去哪

官方資料

• OpenCode Formatters：https://opencode.ai/docs/formatters
• OpenCode Configuration：https://opencode.ai/docs/config
• OpenCode Tools：https://opencode.ai/docs/tools
• OpenCode Permissions：https://opencode.ai/docs/permissions