6.2 代码格式化器

OpenCode内置了20+种代码格式化器，确保AI生成和修改的代码自动符合项目的代码风格规范。

自动格式化功能

当AI创建或修改文件时，OpenCode会自动应用相应的格式化器：

• 写入文件后 - 自动格式化新创建的文件
• 编辑文件后 - 自动格式化修改的部分
• 保存时 - 在文件保存前进行格式化

格式化器会自动检测并使用项目中的配置文件（如.prettierrc、biome.json等）。

内置格式化器

OpenCode内置支持以下格式化器：

格式化器	支持的语言	配置文件
Prettier	JS, TS, CSS, HTML, JSON, YAML, MD	.prettierrc, prettier.config.js
Biome	JS, TS, JSON, CSS	biome.json
ESLint	JS, TS	.eslintrc, eslint.config.js
Ruff	Python	ruff.toml, pyproject.toml
Black	Python	pyproject.toml
autopep8	Python	setup.cfg, tox.ini
gofmt	Go	无需配置
goimports	Go	无需配置
rustfmt	Rust	rustfmt.toml
clang-format	C, C++, Java	.clang-format
shfmt	Shell/Bash	.editorconfig
sql-formatter	SQL	无需配置
terraform fmt	Terraform	无需配置
rubocop	Ruby	.rubocop.yml
mix format	Elixir	.formatter.exs
swift-format	Swift	.swift-format
ktlint	Kotlin	.editorconfig
php-cs-fixer	PHP	.php-cs-fixer.php
stylua	Lua	stylua.toml
zigfmt	Zig	无需配置

配置方法

基本配置结构

{
  "format": {
    "javascript": {
      "command": ["prettier", "--write"],
      "extensions": [".js", ".jsx"],
      "disabled": false
    }
  }
}

指定格式化器

{
  "format": {
    "typescript": {
      "command": ["biome", "format", "--write"]
    },
    "python": {
      "command": ["ruff", "format"]
    },
    "go": {
      "command": ["goimports", "-w"]
    }
  }
}

带选项的配置

{
  "format": {
    "javascript": {
      "command": [
        "prettier",
        "--write",
        "--tab-width", "2",
        "--single-quote",
        "--trailing-comma", "es5"
      ]
    }
  }
}

使用项目本地的格式化器

{
  "format": {
    "typescript": {
      "command": ["npx", "prettier", "--write"]
    },
    "python": {
      "command": ["poetry", "run", "black"]
    }
  }
}

禁用方法

禁用特定语言的格式化

{
  "format": {
    "markdown": {
      "disabled": true
    },
    "json": {
      "disabled": true
    }
  }
}

禁用所有格式化

{
  "format": {
    "*": {
      "disabled": true
    }
  }
}

通过环境变量禁用

# 禁用所有格式化
export OPENCODE_FORMAT_DISABLED=true

# 禁用特定语言
export OPENCODE_FORMAT_DISABLED_PYTHON=true

自定义格式化器

可以为任意文件类型添加自定义格式化器：

添加新格式化器

{
  "format": {
    "custom": {
      "command": ["my-formatter", "--fix"],
      "extensions": [".custom", ".cust"]
    }
  }
}

使用脚本作为格式化器

{
  "format": {
    "special": {
      "command": ["./scripts/format.sh"],
      "extensions": [".special"]
    }
  }
}

链式格式化器

可以通过脚本将多个格式化器串联：

# scripts/format-ts.sh
#!/bin/bash
eslint --fix "$1"
prettier --write "$1"

{
  "format": {
    "typescript": {
      "command": ["./scripts/format-ts.sh"]
    }
  }
}

格式化优先级

当多个格式化器可用时，OpenCode按以下优先级选择：

1. 配置文件中明确指定的格式化器
2. 项目中检测到的格式化器配置文件
3. 系统中安装的默认格式化器

常见配置示例

前端项目（Prettier + ESLint）

{
  "format": {
    "javascript": {
      "command": ["npx", "prettier", "--write"]
    },
    "typescript": {
      "command": ["npx", "prettier", "--write"]
    },
    "css": {
      "command": ["npx", "prettier", "--write"]
    },
    "html": {
      "command": ["npx", "prettier", "--write"]
    }
  }
}

Python项目（Ruff）

{
  "format": {
    "python": {
      "command": ["ruff", "format"]
    }
  }
}

Go项目

{
  "format": {
    "go": {
      "command": ["goimports", "-w"]
    }
  }
}

多语言项目

{
  "format": {
    "typescript": {
      "command": ["npx", "biome", "format", "--write"]
    },
    "python": {
      "command": ["black"]
    },
    "go": {
      "command": ["gofmt", "-w"]
    },
    "rust": {
      "command": ["rustfmt"]
    }
  }
}

故障排除

格式化不生效

• 检查格式化器是否已安装：which prettier
• 确认文件扩展名在extensions列表中
• 检查是否被disabled设置禁用

格式化结果不符合预期

• 检查项目配置文件（如.prettierrc）的设置
• 确认使用的是正确的格式化器
• 尝试在命令行直接运行格式化器测试

下一步

接下来学习如何创建自定义命令，扩展OpenCode的功能。