Aider 上手指南：终端 AI 编程从零开始，BYOK 多模型配置实战

适用人群

三类人：第一次用 Aider 不知道怎么下手的人、装好了但不确定该配哪个模型的人、已经跑了几个任务但 token 消耗太快的人。

这份指南目标是让你在 30 分钟内完成安装 → 配 API key → 跑通第一个任务 → 会写省钱的 Prompt。

Aider 是 AI 编程工具光谱里最极端的一端：没有 GUI、没有自动魔法、所有动作都映射成 git 操作、所有上下文都明确暴露在终端里。学习曲线在 AI 编程工具里最陡，但跨过去之后会上瘾——因为它是唯一一个让你完全掌控 AI 每一步动作的工具。

前置条件

Python 3.9+：Aider 是 Python CLI 工具，需要 pip 安装。Mac/Linux 自带 Python，Windows 建议装 Python 官方安装包或用 WSL
Git 基础：Aider 把 AI 编程映射到 git 工作流，你需要懂 commit / branch / rebase 基本操作
一个 git 仓库：Aider 强制要求在 git 仓库里使用全部功能，非 git 目录功能受限
至少一个 LLM API key：OpenAI / Anthropic / DeepSeek 任选其一（推荐 DeepSeek，最便宜且国内直连）
终端 / 命令行：Aider 没有图形界面，所有操作在终端完成

如果你看到上面的前置条件觉得"太麻烦了"——选 Cursor 或 Claude Code 更合适。Aider 不试图讨好 GUI 用户，它的价值在于可控性，代价是学习成本。

安装

一行命令安装

# 推荐：带 --upgrade-strategy 避免依赖冲突
python -m pip install -U --upgrade-strategy only-if-needed aider-chat

验证安装：

aider --version

国内安装加速

如果 pip 下载慢，换国内镜像：

pip install -U aider-chat -i https://pypi.tuna.tsinghua.edu.cn/simple

Windows 注意事项

Windows 上 Aider 能跑，但 Python 环境 + git CLI 双依赖门槛偏高。推荐用 WSL：

# PowerShell 里装 WSL
wsl --install

# 进 WSL 后按 Linux 方式装
sudo apt update && sudo apt install python3 python3-pip git
pip install aider-chat

如果不用 WSL，确保 Windows 装了 Python（勾选 Add to PATH）和 Git for Windows。

升级

Aider 迭代很快，定期升级：

pip install -U aider-chat

API 配置

Aider 的核心优势是 BYOK（Bring Your Own Key）——你可以接任意模型。以下按推荐优先级配置。

方案 1：DeepSeek（性价比之王，国内首选）

国内直连、支付宝付费、价格极低，是 Aider 的最佳搭档。

# 设置环境变量
export DEEPSEEK_API_KEY=sk-xxxxxxxxxxxxxxxx

# Windows PowerShell
$env:DEEPSEEK_API_KEY = "sk-xxxxxxxxxxxxxxxx"

# 启动 Aider，指定 DeepSeek 模型
aider --model deepseek/deepseek-chat

# 或用 R1 推理模型
aider --model deepseek/deepseek-reasoner

获取 key：打开 platform.deepseek.com，注册后充值（支持支付宝），创建 API key。一次中型 PR（10-15 文件改动）约 $0.05-0.2。

方案 2：Anthropic Claude（编辑能力最稳）

Claude Sonnet 4 在代码编辑能力上是第一梯队，Aider 官方推荐用它做 editor model。

export ANTHROPIC_API_KEY=sk-ant-xxxxxxxxxxxxxxxx

# Windows PowerShell
$env:ANTHROPIC_API_KEY = "sk-ant-xxxxxxxxxxxxxxxx"

# 启动
aider --model claude-sonnet-4-20250514

国内使用需要代理：export HTTPS_PROXY=http://127.0.0.1:7890。一次中型 PR 约 $0.5-2。

方案 3：OpenAI GPT（reasoning 路径）

export OPENAI_API_KEY=sk-xxxxxxxxxxxxxxxx

# Windows PowerShell
$env:OPENAI_API_KEY = "sk-xxxxxxxxxxxxxxxx"

# 启动
aider --model gpt-5
aider --model o3

国内同样需要代理。一次中型 PR 约 $2-5（GPT-5 reasoning）。

方案 4：本地模型（完全离线 + 零成本）

用 Ollama 跑本地模型，隐私场景首选：

# 先装 Ollama 并拉模型
ollama pull qwen2.5:32b

# Aider 接 Ollama
aider --model ollama/qwen2.5:32b

模型质量取决于本机硬件。32B 模型需要 16GB+ 显存或 32GB+ 内存。

方案 5：Architect 双模型组合（进阶）

Aider 独有的杀手锏——把"想方案"和"写代码"拆给两个模型：

aider --architect \
  --model deepseek/deepseek-reasoner \
  --editor-model claude-sonnet-4-20250514 \
  --weak-model gpt-4o-mini

--model（架构师）：DeepSeek-R1 负责高层方案推理
--editor-model：Claude Sonnet 把方案落地成 diff
--weak-model：GPT-4o-mini 生成 commit message

据 Aider 官方 benchmark，DeepSeek R1 + Claude Sonnet 的组合比任一模型单跑高约 10%。

用 .aider.conf.yml 固化配置

不要每次手敲参数。在项目根目录创建 .aider.conf.yml：

# 默认模型组合
model: deepseek/deepseek-reasoner
editor-model: claude-sonnet-4-20250514
weak-model: deepseek/deepseek-chat

# 自动接受所有 diff（个人项目用，团队项目设 false）
yes-always: false

# commit message 模板（中文 + 约定式提交）
commit-prompt: |
  你是项目的 git commit 助手。
  根据 diff 生成中文 commit message，遵循 conventional commits 格式：
  feat/fix/docs/refactor/test/chore: 简短描述

# 默认排除的文件
read-only:
  - docs/
  - public/
  - node_modules/

# 自动加载的项目上下文
read:
  - README.md
  - CONTRIBUTING.md

这一份配置让 Aider 从"通用工具"变成"我的项目的 AI 助手"，等价于 Cursor 的 .cursor/rules/*.mdc，但更精细。

第一个项目实战

第一步：准备 git 仓库

# 如果你已有项目
cd your-project

# 如果是全新项目
mkdir my-project && cd my-project
git init
echo "# My Project" > README.md
git add . && git commit -m "init"

第二步：启动 Aider

aider

进入交互式 REPL。你会看到 Aider 打印出 repo map 扫描结果和当前使用的模型。

第三步：加入要修改的文件

这是新手最容易跳过的一步。Aider 默认只看 repo map（函数签名、类层级），看不到文件实现细节。你要修改的文件必须 /add 显式加入：

/add src/server.ts src/api/user.ts

第四步：用自然语言下指令

> 把 server/api/user.ts 里的 getUserById 改成支持批量查询，
> 参数从 id: string 改成 ids: string[]，返回 User[] 而不是 User。
> 同时更新调用方代码。

Aider 会：

分析你 add 的文件 + repo map 里的相关文件
给出修改方案（等确认）
生成 diff 并自动 git add + git commit
commit message 由 weak-model 自动生成

第五步：验证和回滚

# 看刚才的改动
git log --oneline -3
git diff HEAD~1

# 不满意？一行回滚
git reset --hard HEAD~1

# 或用 Aider 的 /undo
/undo

实战注意

先创建分支再跑：git checkout -b aider/user-batch-query，避免主分支被污染
任务描述要具体：说清楚改什么、怎么改、影响哪些文件，Aider 不会自己猜
一次一个任务：不要在一个对话里塞 5 个不相关的修改，token 消耗会暴增

Git 工作流

Aider 的 git 集成是它与所有竞品的最大区别。掌握以下工作流是用好 Aider 的关键。

标准工作流

1. git checkout -b aider/<task-name>     # 创建实验分支
2. aider                                   # 启动 Aider
3. /add <相关文件>                         # 加入要修改的文件
4. <自然语言描述任务>                       # 让 AI 改代码
5. git diff                               # 检查改动
6. 满意 → git checkout main && git merge aider/<task-name>
   不满意 → git reset --hard HEAD~1       # 回滚
7. /exit                                   # 退出 Aider

常用 Aider 命令

命令	用途
`/add <file>`	把文件加入对话（AI 能看到实现细节）
`/drop <file>`	把文件移出对话
`/undo`	撤销上一次 Aider commit
`/diff`	查看当前未提交的改动
`/commit`	手动提交当前改动
`/run <cmd>`	在 Aider 里跑 shell 命令
`/clear`	清空对话历史（开始新任务时用）
`/save <file>`	保存当前对话到文件
`/load <file>`	加载之前保存的对话
`/tokens`	查看当前 token 消耗
`/model <name>`	切换模型
`/architect`	切换到 Architect 双模型模式

commit 历史整理

Aider 一次复杂任务可能产生 5-15 个 commit，commit message 质量参差。合并回主分支前要整理：

# squash 成一个 clean commit
git checkout main
git merge --squash aider/<task-name>
git commit -m "feat: user 支持批量查询"

省 token 技巧

Aider 的 token 消耗完全可控——前提是你知道怎么控制。以下 7 个技巧按效果排序。

1. 用 DeepSeek 替代 Claude / GPT

同一个任务，DeepSeek 比 Claude 便宜 10-30 倍，推理/编辑能力达到 Claude 的 80% 左右。日常任务用 DeepSeek，复杂任务再切 Claude。

2. 精确 /add，不要 /add 整个目录

/add src/ 会把整个 src 目录塞进上下文，token 暴增。只 /add 你要改的文件，Aider 通过 repo map 已经知道其他文件的接口签名。

3. 任务描述具体到文件 + 函数 + 行为

烧 token 的写法：

> 帮我优化一下性能

Aider 会全仓库扫描找瓶颈，token 爆炸。

省 token 的写法：

> 把 src/api/user.ts 里的 getUserById 的数据库查询从 N+1 改成批量查询，
> 用 WHERE id IN (?) 替代循环里逐个 SELECT

任务被锁定到具体函数和具体改动，Aider 直接走最优路径。

4. 用 /clear 开新任务，不要在一个对话里做太多

对话越长，每次请求都要把全部历史发给模型，token 线性增长。每完成一个任务 /clear 一次。

5. weak-model 用最便宜的

commit message 不需要 SOTA 智能。DeepSeek-V3 / GPT-4o-mini / Claude Haiku 都够。在 .aider.conf.yml 里设 weak-model: deepseek/deepseek-chat，省下来的 token 很可观。

6. 用 read-only 标记不该看的文件

# .aider.conf.yml
read-only:
  - docs/
  - public/
  - node_modules/
  - "*.test.ts"

避免 Aider 把无关文件塞进上下文。

/add src/<相关文件1> src/<相关文件2>

我要加一个<功能描述>功能。
要求：
1. 在 src/<模块>/ 目录下新建 <FileName>，实现核心逻辑
2. 在 src/<入口文件> 里接入调用
3. 遵循现有代码风格（命名、错误处理、日志）
4. 不要动其他模块，只改我 add 的文件 + 新建文件
5. 如果需要新依赖，先告诉我，不要自己加 package.json

先告诉我你的方案，我确认后再动手。

2. Bug 修复

/add src/<出 bug 的文件>

<文件>里的<函数名>有 bug：<描述 bug 现象 + 复现步骤>。

预期行为：<正确行为>
实际行为：<错误行为>

要求：
1. 找到 root cause，不要只修表面症状
2. 修复后加一个测试用例覆盖这个场景
3. 检查同模块里有没有类似的 bug
4. commit message 用 fix: 前缀

3. 重构

/add src/<要重构的文件1> src/<要重构的文件2>

把<模块名>做以下重构：
1. 把<大函数>拆成 3 个小函数，每个只做一件事
2. 提取重复逻辑到 utils
3. 类型从 any 改成具体类型
4. 不改变外部行为，测试必须全绿

要求：
- 每一步拆成独立 commit
- 每次改动后跑 npm test 确认没 break
- commit message 用 refactor: 前缀

4. 代码审查

/add src/<要审查的文件>

审查这个文件的代码质量，关注：
1. 安全漏洞（SQL 注入、XSS、敏感信息泄露）
2. 性能问题（N+1 查询、不必要的循环、内存泄漏）
3. 错误处理是否完整（边界条件、异常捕获）
4. 类型安全（any 滥用、类型断言风险）
5. 可读性（命名、注释、函数长度）

产出：按严重程度排序的问题列表，每个问题给出修复建议。
不要直接改代码，只做分析。

5. 测试生成

/add src/<要测试的文件>

为<文件名>里的所有导出函数生成单元测试。
要求：
1. 用 vitest（或 jest / pytest，根据项目配置）
2. 每个函数至少 3 个用例：正常输入 + 边界值 + 异常输入
3. mock 外部依赖（数据库、API 调用）
4. 测试文件放在 __tests__/ 目录，文件名 <原文件名>.test.ts
5. 覆盖率目标 80%+
6. 跑一遍测试确认全绿

常见坑

安装 / 配置

pip install 报依赖冲突：用 --upgrade-strategy only-if-needed 参数，或用 pipx install aider-chat 隔离环境
API key 没生效：检查环境变量是否正确设置，echo $DEEPSEEK_API_KEY 验证
Ollama 本地模型超 context 不报错：静默截断会让你以为"模型忘了我加的文件"。明确配置 num_ctx
Windows 路径问题：用 WSL 最省心，纯 Windows 确保用正斜杠路径

任务 / 执行

没在 git 仓库里跑会被警告：Aider 强烈建议 git init 后再用，否则 /undo 不能用
/add 之前的文件不会被看见：和 Cursor @codebase 不同，Aider 默认只看 repo map，要修改的文件要显式 /add
/undo 不是"撤销修改"：它撤销的是上一次 Aider commit，已被你后续手动修改过的文件不会被撤销
--yes-always 太激进：会跳过所有确认，包括"是否要把这个文件加入 chat"——容易让 Aider 偷偷读你不想给模型看的文件

Architect 模式

editor model 不能用推理模型：o3 / R1 当 editor 生成的 diff 经常不符合 unified diff 格式，应用失败率高。editor 必须用 Claude Sonnet / GPT-4.1 这类指令遵循能力好的模型
Architect 模式有 prompt injection 风险：不要在不可信项目上开 architect mode + --yes 组合，README 被塞了攻击指令可能诱导 editor 生成后门代码

和其他工具的衔接

和 Cursor 一起用：Aider 做 git 工作流重的修改，Cursor 做 inline 补全 + 快速跳转
和 Claude Code 一起用：Aider 做日常小改 + 多模型试验，Claude Code 做长任务 + 复杂重构
和 GitHub Copilot 一起用：Copilot 做代码补全，Aider 做多文件修改 + commit

上线前 checklist

Python 3.9+ 已安装，aider --version 能跑
至少一个 API key 已配置（推荐 DeepSeek + 支付宝）
.aider.conf.yml 已创建，默认模型 + commit 模板已设好
已在 git 仓库里跑通第一个任务
已知道 /add /undo /clear /tokens 四个核心命令
已收藏 3-5 个 Prompt 模板，避免每次从零写
已知道 Architect 模式的使用场景和注意事项
备好一个 GUI 替代（Cursor / Claude Code），Aider 不适合的场景可切换

Aider 上手指南：终端 AI 编程从零开始，BYOK 多模型配置实战

相关工具