OpenCode 中文社区

Appearance

5.18 代码格式化器 ​

💡 一句话总结：配置统一的代码格式化工具，让 AI 和团队保持一致的代码风格。

学完你能做什么 ​

  • 配置项目使用的代码格式化工具
  • 让 OpenCode 自动按照项目风格格式化代码
  • 解决 AI 生成代码格式不一致的问题
  • 团队协作时保持代码风格统一

你现在的困境 ​

  • AI 生成的代码格式与项目不一致
  • 每次都需要手动调整格式
  • 团队成员代码风格各异
  • 不知道如何让 AI 遵循项目的格式规范

什么时候用这一招 ​

  • 当你需要：让 AI 输出的代码符合项目格式规范
  • 而且不想：每次手动调整代码格式

🎒 开始前的准备 ​

确保你已经完成以下事项：

核心思路 ​

OpenCode 如何处理代码格式 ​

OpenCode 支持两种格式化方式：

方式原理适用场景
LSP Format使用语言服务器的格式化功能支持的项目，IDE 自带
外部 Formatter调用项目配置的格式化工具需要配置文件

格式化工具优先级 ​

  1. LSP Format（优先）

    • VS Code 内置格式化
    • Prettier Extension
    • ESLint Extension

  2. 外部 Formatter（LSP 不可用时）

    • Prettier
    • Black (Python)
    • Gofmt (Go)
    • stylua (Lua)

支持的格式化工具 ​

JavaScript / TypeScript ​

Prettier ​

配置文件识别：

  • .prettierrc
  • .prettierrc.json
  • .prettierrc.yml
  • .prettierrc.yaml
  • prettier.config.js
  • prettier.config.cjs
  • .prettierrc.js
  • .prettierrc.cjs
  • package.json 中的 prettier 字段

示例配置：

json
// .prettierrc
{
  "semi": true,
  "trailingComma": "es5",
  "singleQuote": false,
  "printWidth": 80,
  "tabWidth": 2,
  "useTabs": false
}

ESLint (fix) ​

配置文件识别：

  • .eslintrc
  • .eslintrc.json
  • .eslintrc.yml
  • .eslintrc.yaml
  • .eslintrc.js
  • .eslintrc.cjs
  • package.json 中的 eslintConfig 字段

示例配置：

json
// .eslintrc.json
{
  "extends": "eslint:recommended",
  "rules": {
    "indent": ["error", 2],
    "quotes": ["error", "double"],
    "semi": ["error", "always"]
  }
}

Python ​

Black ​

配置文件识别：

  • pyproject.toml 中的 [tool.black] 段
  • .black.toml
  • setup.cfg 中的 [black] 段

示例配置：

toml
# pyproject.toml
[tool.black]
line-length = 88
target-version = ['py38']
include = '\.pyi?$'
extend-exclude = '''
/(
  # directories
  \.eggs
  | \.git
  | \.hg
  | \.mypy_cache
  | \.tox
  | \.venv
  | build
  | dist
)/
'''

Autopep8 ​

配置文件识别：

  • setup.cfg 中的 [pycodestyle] 段
  • .pylintrc
  • pyproject.toml 中的 [tool.autopep8] 段

Yapf ​

配置文件识别：

  • .style.yapf
  • setup.cfg 中的 [yapf] 段
  • pyproject.toml 中的 [tool.yapf] 段

Go ​

gofmt ​

Go 自带格式化工具，无需额外配置。

使用 Go 标准格式化规则。

goimports ​

自动导入和移除未使用的导入。

Rust ​

rustfmt ​

配置文件识别：

  • rustfmt.toml
  • .rustfmt.toml

示例配置：

toml
# rustfmt.toml
max_width = 100
hard_tabs = false
tab_spaces = 4
newline_style = "Unix"
use_small_heuristics = "Default"
reorder_imports = true

Java ​

Google Java Format ​

配置文件识别：

  • 通过 IDE 插件配置

CSS / SCSS / Less ​

Prettier ​

Prettier 也支持样式文件的格式化，配置与 JS/TS 相同。

HTML ​

Prettier ​

Prettier 支持 HTML 格式化。

HTML Tidy ​

配置文件识别：

  • .htmltidyrc

JSON / YAML ​

Prettier ​

Prettier 支持 JSON 和 YAML 格式化。

jq (JSON only) ​

JSON 命令行格式化工具。

其他语言 ​

语言推荐工具配置文件
C / C++clang-format.clang-format
C#dotnet-format.editorconfig
PHPPHP CS Fixer.php-cs-fixer.php
RubyRuboCop.rubocop.yml
SwiftSwiftFormat.swiftformat
Luastyluastylua.toml

配置步骤 ​

方法 1：使用 LSP Format（推荐） ​

适用场景：VS Code 已安装格式化插件

  1. 在 VS Code 中安装格式化插件

    • Prettier - Code formatter
    • ESLint

  2. 配置 VS Code 格式化设置

json
// .vscode/settings.json
{
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "[javascript]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  },
  "[typescript]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  },
  "[python]": {
    "editor.defaultFormatter": "ms-python.black-formatter"
  }
}
  1. OpenCode 会自动使用 LSP 格式化功能

方法 2：使用外部 Formatter ​

适用场景：项目中有格式化工具配置

  1. 确保项目中已安装格式化工具
bash
# JavaScript/TypeScript
npm install --save-dev prettier eslint

# Python
pip install black autopep8

# Go
# 无需安装，自带

# Rust
rustup component add rustfmt

  1. 在项目根目录创建配置文件

  2. OpenCode 会自动检测并使用配置的格式化工具

高级配置 ​

指定格式化工具 ​

如果项目有多个格式化工具，可以指定使用哪一个：

yaml
# AGENTS.md (在 OpenCode 配置中)
formatters:
  javascript: prettier
  typescript: prettier
  python: black
  go: gofmt
  rust: rustfmt

格式化选项 ​

可以覆盖默认的格式化选项：

yaml
formatters:
  prettier:
    options:
      semi: true
      singleQuote: false
      tabWidth: 2

禁用格式化 ​

如果某些文件不想被格式化：

yaml
formatters:
  excludes:
    - "dist/**"
    - "build/**"
    - "*.min.js"

跟我做 ​

实战 1：为 JavaScript 项目配置 Prettier ​

目标：配置 Prettier，让 AI 生成的代码符合项目风格

  1. 在项目根目录创建 .prettierrc：
bash
cat > .prettierrc << 'EOF'
{
  "semi": true,
  "trailingComma": "es5",
  "singleQuote": false,
  "printWidth": 100,
  "tabWidth": 2,
  "useTabs": false
}
EOF
  1. 验证配置是否生效：
bash
npx prettier --check "src/**/*.{js,ts,jsx,tsx}"
  1. 在 OpenCode 中测试：
创建一个组件文件，使用函数式组件 + hooks

你应该看到：AI 生成的代码自动符合 Prettier 格式

实战 2：为 Python 项目配置 Black ​

目标：配置 Black，统一 Python 代码风格

  1. 在 pyproject.toml 中添加 Black 配置：
toml
[tool.black]
line-length = 88
target-version = ['py38']
include = '\.pyi?$'
  1. 安装 Black：
bash
pip install black
  1. 验证配置：
bash
black --check .
  1. 在 OpenCode 中测试：
创建一个 Python 类，包含几个方法和文档字符串

你应该看到：AI 生成的 Python 代码符合 Black 格式

实战 3：配置 ESLint 自动修复 ​

目标：让 AI 在生成代码时自动应用 ESLint 规则

  1. 安装 ESLint：
bash
npm install --save-dev eslint
npx eslint --init
  1. 创建 .eslintrc.json：
json
{
  "env": {
    "browser": true,
    "es2021": true,
    "node": true
  },
  "extends": "eslint:recommended",
  "parserOptions": {
    "ecmaVersion": "latest",
    "sourceType": "module"
  },
  "rules": {
    "indent": ["error", 2],
    "linebreak-style": ["error", "unix"],
    "quotes": ["error", "double"],
    "semi": ["error", "always"],
    "no-unused-vars": "warn"
  }
}
  1. 在 VS Code 中配置自动修复：
json
// .vscode/settings.json
{
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": true
  }
}
  1. 在 OpenCode 中测试：
创建一个有潜在 ESLint 警告的函数

你应该看到：AI 生成的代码遵循 ESLint 规则

📋 格式化工具对比 ​

JavaScript / TypeScript ​

工具优点缺点适用场景
Prettier无需配置、风格一致不太灵活常规项目
ESLint可自定义规则配置复杂有特定规范的项目
两者结合灵活 + 一致需要协调大型项目

Python ​

工具优点缺点适用场景
Black零配置、PEP 8无法自定义大部分项目
Autopep8灵活、PEP 8需要配置有特定需求
YapfGoogle 风格非标准Google 项目

检查点 ✅ ​

全部通过才能继续

  • [ ] 为项目配置了至少一个格式化工具
  • [ ] AI 生成的代码符合项目格式规范
  • [ ] 理解了不同语言的格式化工具
  • [ ] 掌握了配置文件的写法

踩坑提醒 ​

现象原因解决
AI 生成的代码没有格式化配置文件未生效检查配置文件名和位置
格式化规则冲突多个格式化工具冲突只保留一个，或明确优先级
某些文件格式化失败文件编码或路径问题检查文件编码和路径
团队成员格式不一致没有统一配置共享配置文件到 Git

最佳实践 ​

1. 提交配置文件到版本控制 ​

bash
git add .prettierrc .eslintrc.json pyproject.toml
git commit -m "chore: add formatter config"

2. 使用 editorconfig ​

创建 .editorconfig 统一基础设置：

ini
root = true

[*]
charset = utf-8
end_of_line = lf
insert_final_newline = true
trim_trailing_whitespace = true

[*.py]
indent_style = space
indent_size = 4

[*.{js,ts,json}]
indent_style = space
indent_size = 2

3. 配置 CI/CD ​

在 GitHub Actions 或其他 CI 中添加格式检查：

yaml
# .github/workflows/format-check.yml
name: Format Check
on: [push, pull_request]
jobs:
  format:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: 18
      - run: npm ci
      - run: npm run format:check

4. 使用 pre-commit hooks ​

bash
# 安装 husky
npm install --save-dev husky lint-staged
npx husky install

# 配置 pre-commit
npx husky add .husky/pre-commit "npx lint-staged"

在 package.json 中配置：

json
{
  "lint-staged": {
    "*.{js,ts,jsx,tsx}": ["prettier --write", "eslint --fix"],
    "*.{py}": ["black"]
  }
}

本课小结 ​

你学会了：

  1. OpenCode 支持的代码格式化工具
  2. 如何为不同语言配置格式化工具
  3. LSP Format 和外部 Formatter 的区别
  4. 配置文件的正确写法
  5. 团队协作时统一代码风格的最佳实践

下一课预告 ​

下一课我们将学习 LSP 服务器配置，了解如何为不同语言配置语言服务器，提升代码智能提示和跳转功能。

📚 更多完整模板：Prompt 模板库

微信群