更新于

Aider 中文配置与最佳实践

Aider命令行工具GitAPI 中转配置教程

Aider 走的是命令行结对编程路线：每次对话直接产出 git commit。它不需要 VSCode 插件、不依赖订阅，对国内开发者非常友好——前提是把 base_url 接对。

一、安装与基础配置

# 推荐用 pipx 隔离
python -m pip install --user pipx
pipx install aider-install
aider-install

或直接：

pip install -U aider-chat

确认安装：aider --version 显示版本号即可。

二、最小可用配置

Aider 通过环境变量或 .aider.conf.yml 读配置。最小用例：

export OPENAI_API_BASE="https://yotradeapi.com/v1"
export OPENAI_API_KEY="sk-your-yotrade-key"

cd your-project
aider --model openai/claude-sonnet-4-6

要点：

  • Aider 用 LiteLLM 做底层，openai/ 前缀告诉它走 OpenAI 兼容协议。
  • 模型名要用网关支持的写法。
  • 进入会话后 /help 看全部命令。

三、推荐配置文件

在项目根放一个 .aider.conf.yml：

# 默认模型
model: openai/claude-sonnet-4-6
# Architect 模式时的 weak model
weak-model: openai/claude-haiku-4-5
# Architect 模式开关
architect: true
# 自动 git commit
auto-commits: true
# 但不自动推送
gitignore: true
# 显示 token 消耗
show-model-warnings: true
# 流式输出
stream: true
# 编辑器 diff 风格
edit-format: diff
# 中文提示
prompt-prefix: "请用中文回复。"

把 API Key 放 .aider.conf.yml 同目录的 .env：

OPENAI_API_BASE=https://yotradeapi.com/v1
OPENAI_API_KEY=sk-your-yotrade-key

并加进 .gitignore。

四、Architect / Editor 双模型策略

Aider 的「Architect 模式」会用两个模型：

  • Architect：推理强，负责设计与分析（贵）
  • Editor：写代码快，负责实际改 diff（便宜）

启用方法：

aider --architect \
  --model openai/claude-opus-4-7 \
  --editor-model openai/claude-sonnet-4-6

或在配置里：

architect: true
model: openai/claude-opus-4-7
editor-model: openai/claude-sonnet-4-6

这种组合在国内中转下特别划算：Opus 处理一次复杂规划，Sonnet 干粗活，单任务能省 30–50% 而效果不输。

五、Repomap：让 Aider 看懂整个仓库

Aider 默认只把你 /add 的文件加进上下文。但通过 repomap，它能用很少的 token 让 LLM 大致理解整个项目结构。

控制 repomap 大小：

aider --map-tokens 2048   # 默认 1024，大项目可以拉到 4096

如果 repomap 卡住或耗时太久：

aider --no-auto-commits --map-tokens 0   # 完全禁用

实战建议：

  • 小项目（< 50 文件）：repomap 0，靠 /add 显式加文件
  • 中等项目：默认 1024 够用
  • 大型 monorepo：用 .aiderignore 排除 node_modules、dist、生成文件后再开 2048

六、命令速查

命令作用
/add path把文件加进上下文
/drop path移出上下文
/ls看当前上下文里的文件
/diff看 Aider 最近改了什么
/undo撤销最后一次 commit
/commit手动 commit
/test cmd跑测试，失败自动让 LLM 修
/run cmd跑命令，把输出加进上下文
/tokens看当前上下文的 token 数
/clear清空对话（保留文件）
/reset完全重置
/web url抓网页加进上下文
/model name切模型
/copy复制最后一次 LLM 回复
/exit退出

七、git 工作流

Aider 默认每次成功修改都 git commit -m "aider: ..."。这是它最大的卖点：

* aider: 添加 retry 装饰器到 fetch_data
* aider: 修复 type hint，统一返回 dict
* (上一手提交)

回滚一步用 /undo 即可，相当于 git reset --hard HEAD~1。

如果你不想自动 commit：

auto-commits: false
dirty-commits: false

然后手动 git add + git commit。

八、流式 + 长上下文的稳定性

国内中转下 Aider 长任务最容易遇到的问题：

  1. 流式中断：表现为 LLM 回复到一半卡住。Aider 会重试，但会消耗双倍 token。
    缓解：换模型或在网关侧开 keep-alive；如果连续断三次，重启 aider。
  2. 大文件 diff 过长：超过 8k tokens 的 diff，LLM 经常生成无效格式。
    缓解：--edit-format whole（整文件替换），更稳但更贵。
  3. repomap 失效：仓库里有大量二进制或自动生成文件。
    缓解：完善 .aiderignore。

九、配合 Lint / Test 的”闭环”用法

Aider 真正强大的地方是闭环：

aider --auto-test --test-cmd "npm test" --auto-lint --lint-cmd "npm run lint"

每次它改完文件，会自动跑 test 和 lint，失败的话把错误信息加进上下文让 LLM 自己修。我用这个模式重构 100 多文件的 Node 项目，模型大概会出错 2–3 次，但都能在三轮内自我修复。

十、Aider 与 Cline / Claude Code 的差异

维度AiderClineClaude Code
界面CLIVSCodeCLI
改文件方式git commit直接保存Edit 工具
自动 commit强无无
Plan/ArchitectArchitect 模式Plan/ActPlan Mode
上下文管理repomap + /add@-mentionsAuto + /context
适合规模中小型仓库单任务长任务

如果你的工作流是 “git-first” 的——所有改动必须可回滚、必须有清晰提交历史——Aider 是最自然的选择。

十一、相关阅读

需要支持 Aider Architect 模式（双模型）的中转？YoTradeApi 提供 Claude Sonnet 4.6 + Opus 4.7 + Haiku 4.5 同 Key 调用，配置 base_url 直接接入。

相关阅读