第一章 认识 Aider

🎯 本章目标： 了解 Aider 是什么、能干什么、判断它是否适合你。

1.1 什么是 Aider

Aider 是一个开源的终端 AI 编程工具，运行在命令行中，能够直接读取你的整个代码库、理解项目结构、自动编辑文件、并生成有意义的 Git 提交记录。与普通的 AI 聊天不同，Aider 不是简单地回答你的问题——它会真正地动你的代码。

Aider 项目由 Paul Gauthier 创建并维护，GitHub 上超过 45,000 颗星标。截至 2025 年，Aider 已处理超过 150 亿个 token 的代码任务，在 OpenRouter 平台排名 Top 20。最令人印象深刻的是：Aider 最新版本中 88% 的新代码是由 Aider 自己编写的——这个指标被称为"奇点率"（Singularity），说明这个工具已经足够成熟到能辅助开发自己。

你可以把 Aider 想象成一位坐在你旁边的资深开发者：你提出需求，它帮你写代码、重构、修 bug，并且每一步改动都有迹可循。每次修改都会自动产生一个 Git 提交，你可以随时 git diff 查看改动，不满意的用 git reset 一键回滚。

1.2 核心特性

• 多 LLM 支持 — 支持 Claude 3.7 Sonnet、DeepSeek R1/Chat V3、OpenAI o1/o3-mini/GPT-4o，以及几乎所有主流云模型和本地模型（Ollama）
• 代码地图（Repo Map） — 自动为整个项目构建结构索引，帮助 LLM 理解文件之间的依赖关系
• 100+ 编程语言 — 覆盖 Python、JavaScript、TypeScript、Rust、Ruby、Go、C++、PHP、HTML、CSS 等
• 自动 Git 提交 — 每次修改后自动生成有意义的 commit message，方便审查和回滚
• IDE 集成 — 从 VS Code、JetBrains、Emacs 等编辑器中直接调用
• 图片和网页上下文 — 可附加截图、设计稿、文档 URL 作为参考
• 语音编程 — 对着麦克风说话，Aider 将语音转成代码修改
• 自动 Lint & 测试 — 每次修改后自动运行 linter 和测试，发现故障自动修复

1.3 Aider 的工作原理

当你启动 Aider 并加载项目后，它会执行以下步骤：

1. 扫描代码库 — 读取所有源文件，提取类、函数、变量的定义位置，构建代码地图
2. 启动交互会话 — 在终端中出现 > 提示符，等待你输入自然语言指令
3. 分析并规划 — 结合代码地图和你的指令，决定需要修改哪些文件的哪些位置
4. 执行修改 — 自动编辑文件内容，生成原子化的 diff 修改
5. 自动提交 — 每次修改后自动 git add + git commit，commit message 由 AI 自动生成
6. Lint & 修复 — 如果开启检查，在提交前运行 linter，发现问题自动修复

1.4 系统要求

第二章 快速上手（5 分钟）

最快的体验方式：使用 pip 安装 Aider 安装器。整个过程只需几分钟。

2.1 第一步：安装

在终端中执行以下命令（实测通过 ✅）：

python -m pip install aider-install

实测输出：

Successfully installed aider-install-0.1.0

3.2 第二步：配置

设置 API Key。Aider 支持多个 LLM 提供商，根据你使用的模型设置对应的环境变量：

# 如果使用 OpenAI 模型（GPT-4o, o1 等）
export OPENAI_API_KEY=sk-your-openai-key-here

# 如果使用 Anthropic 模型（Claude 3.7 Sonnet 等）
export ANTHROPIC_API_KEY=sk-ant-your-anthropic-key-here

# 如果使用 DeepSeek 模型
export DEEPSEEK_API_KEY=sk-your-deepseek-key-here

你也可以在项目根目录创建 .env 文件，把上面的内容放进去，Aider 会自动读取。

2.3 第三步：运行

切换到你想要操作的项目目录，然后启动 Aider：

cd /path/to/your/project
aider

启动后，Aider 会自动扫描项目文件，显示识别到的代码文件列表，并在底部显示 > 提示符等待你的指令。

2.4 第四步：第一条指令

在 > 提示符后输入你的第一个需求：

> 帮我给这个项目添加一个 README.md 文件，描述项目的功能和用法

Aider 会分析项目结构，生成 README.md 内容，保存文件并自动执行 Git 提交。

2.5 第五步：验证

使用以下命令查看 Aider 自动生成的 Git 提交记录：

git log --oneline -5

你会看到类似以下输出：

abc1234 add README.md with project description
def5678 Initial commit

💡 提示： 如果不想让 Aider 自动提交，可以用 --no-auto-commits 参数启动。新手推荐保留自动提交——这是最安全的工作方式。

第三章 安装指南（全平台）

本章详细介绍多种安装方式，方便你在不同环境中快速部署。

3.1 方式一：pip 安装（推荐新手）

最简单的安装方式，一条命令搞定：

python -m pip install aider-install

实测结果： 命令执行成功，输出 Successfully installed aider-install-0.1.0。安装后即可在终端中使用 aider 命令。

3.2 方式二：从源码安装

如果你需要最新的开发版功能：

git clone https://github.com/Aider-AI/aider.git
cd aider
python -m pip install -e .

依赖说明（来自 pyproject.toml 和 requirements.txt）：

• Python 版本要求：>=3.10, <3.15
• 核心依赖：aiohttp、litellm、pydantic、httpx、typer、fastapi 等
• 可选依赖：与不同 LLM 提供商相关的扩展包

3.3 方式三：pipx 安装（推荐隔离环境）

pipx 可以将 Aider 安装在隔离环境中，避免依赖冲突：

pipx install aider-chat

💡 注意 PyPI 上的包名是 aider-chat，而安装器包名是 aider-install。日常使用推荐先用 aider-install 方式。

3.4 方式四：Docker 安装

docker pull paulgauthier/aider
docker run -it --rm \
  -v $(pwd):/app \
  -e OPENAI_API_KEY=sk-your-key \
  paulgauthier/aider

3.5 验证安装

执行以下命令确认安装成功：

aider --version

预期输出：

aider v0.86.0

💡 提示： 如果安装遇到问题，请先检查网络连接和 Python 版本（需要 3.10+），然后参考第九章常见问题。

第四章 核心功能

4.1 代码地图（Repo Map）

Aider 最核心的能力之一是自动构建"代码地图"。当你加载项目时，Aider 会扫描所有源文件，提取类、函数、全局变量的定义位置，形成一个结构化的索引。这个索引被压缩后作为上下文发送给 LLM，让 AI 知道"这个函数定义在哪个文件的第几行"、"这个类有哪些方法"等关键信息。

对于 Git 仓库，Aider 利用 git ls-files 获取文件列表，自动跳过 .gitignore 中的文件。默认代码地图大小控制在 2048 token 以内，足以覆盖中等规模项目的核心结构。你可以用 --map-tokens 参数调整这个上限。

4.2 自动 Git 集成

这是 Aider 最受用户欢迎的特性。每次 AI 完成修改后，Aider 自动执行：

• git add <changed_files> — 暂存所有修改
• git commit -m "自动生成的描述" — 提交并生成有意义的 commit message

这意味着：每项修改都是独立的原子提交，commit message 由 AI 总结描述清晰，你可以随时用 git log --oneline 查看全部改动历史，不满意的地方直接用 git reset HEAD~1 回退。

4.3 多 LLM 提供商支持

Aider 通过 litellm 库连接到各大 LLM 提供商：

4.4 Lint & 测试自动修复

Aider 可以在每次修改后自动运行 linter（如 flake8、eslint、ruff 等）和测试。如果发现语法错误或风格问题，Aider 会自动尝试修复。这是一个"自我修正"循环：改代码 → 检查 → 发现问题 → 自动修复 → 再次检查 → 直到通过。

启用方式：

aider --lint --test

4.5 图片和网页上下文

你可以在对话中附加图片或网页链接作为上下文：

• 上传 UI 设计截图，让 AI 照着实现前端代码
• 粘贴错误页面的截图，帮助 AI 理解问题
• 提供 API 文档 URL，让 AI 编码时参考

> /add screenshot.png 帮我实现这个设计
> /web https://api.example.com/docs 参照文档实现客户端

4.6 语音编程

Aider 支持语音输入，直接对着麦克风说出需求，Aider 会转换成文字并执行：

aider --voice

第五章 进阶用法

5.1 编辑格式（Edit Formats）

Aider 支持多种编辑格式，你可以根据使用的模型选择最合适的：

• diff — 默认格式，AI 输出 unified diff 格式的修改，Aider 自动应用
• whole — AI 输出完整文件内容，Aider 用新内容替换旧文件，适合小文件
• udiff — 类似 diff 但使用更通用的 unified diff 格式
• editor-diff — 与编辑器集成时的专用格式

手动指定编辑格式：

aider --edit-format diff

5.2 限定文件范围

你可以明确告诉 Aider 要操作哪些文件，而不是让 AI 自动选择：

aider src/main.py src/utils.py tests/

5.3 只读模式（Read-Only Files）

有些文件你希望 AI 读取作为参考但不希望它修改，用 --read：

aider --read docs/architecture.md --read requirements.txt

5.4 自定义 Prompt 指令

通过 ~/.aider.conf.yml 配置文件自定义行为：

# ~/.aider.conf.yml
model: claude-3-7-sonnet-20250219
edit-format: diff
auto-commits: true
lint: true
test: true
prompt-suffix: "请使用 TypeScript 风格指南，优先使用 const 而非 let。"

5.5 在 IDE 中使用 Aider

Aider 可以集成到主流编辑器中。以 VS Code 为例：

1. 打开 VS Code 终端（Ctrl + `）
2. 在项目目录中运行 aider
3. 在代码注释中写需求，Aider 会自动识别并修改
4. 或使用 --watch-files 模式监视文件变化

对于 Emacs 用户，社区有 aidermacs 包提供深度集成。对于 Neovim，也有对应的插件支持。

5.6 用量统计

Aider 可以统计 token 使用量和 API 调用次数，帮助你了解每个任务的成本：

aider --analytics
aider --stats

第六章 实战场景

6.1 场景一：用 Aider 开发一个 Python CLI 工具

假设你要从零开始构建一个简单的命令行待办事项管理器（Todo CLI），包含添加任务、列出任务、标记完成三个功能。通过 Aider，你只需要用自然语言描述需求，剩下的代码编写工作由 Aider 自动完成。

第一步：初始化项目

在终端中创建项目目录并初始化 Git 仓库，然后启动 Aider：

mkdir todo-cli
cd todo-cli
git init
aider --model gpt-4o

第二步：下达完整需求

Aider 启动后，在 > 提示符下输入详细的需求描述：

> 帮我创建一个 Python CLI 待办事项管理工具。要求：
1. 使用 click 库实现命令行界面
2. 数据存储在本地的 JSON 文件中
3. 支持三个命令：add（添加任务）、list（列出所有任务）、done（标记任务为已完成）
4. 每个任务有 id、内容（description）、创建时间（created_at）、状态（done: bool）四个字段
5. add 命令接受一个字符串参数作为任务内容
6. list 命令默认显示所有未完成的任务，加 --all 参数显示全部
7. done 命令接受任务 id 作为参数
8. 给 tasks.json 加上合理的初始结构

Aider 会分析需求，自动创建 todo.py 和 tasks.json 文件。完成后显示类似：

✓ Created todo.py
✓ Created tasks.json
Commit abc1234: feat: create Todo CLI with add, list, and done commands

第三步：测试运行

退出 Aider（输入 /exit），测试生成的工具：

python todo.py add "学习 Aider 教程"
python todo.py add "写一个实战项目"
python todo.py add "复习 Git 用法"
python todo.py list --all
python todo.py done 1
python todo.py list

预期输出：

# python todo.py add "学习 Aider 教程"
✓ 已添加任务：学习 Aider 教程 (id: 1)

# python todo.py list --all
[1] 学习 Aider 教程 - ❌ 未完成
[2] 写一个实战项目 - ❌ 未完成
[3] 复习 Git 用法 - ❌ 未完成

# python todo.py done 1
✓ 任务 #1 已标记为完成

# python todo.py list
[2] 写一个实战项目 - ❌ 未完成
[3] 复习 Git 用法 - ❌ 未完成

整个过程大约 2-3 分钟。如果对生成的代码不满意，只需继续在 Aider 中下达修改指令：

> list 命令的输出格式改成表格形式，用 tabulate 库

Aider 会自动定位到相关代码段进行精确修改并再次提交。这种迭代式开发让你可以专注于表达"想要什么"，而不是纠结于"怎么写"。

6.2 场景二：用 Aider 为 JavaScript 项目添加单元测试

假设你有一个现有的 JavaScript 项目（一个数学工具库），需要为它补全单元测试。这个场景展示了 Aider 在已有代码库上的工作能力。

第一步：准备项目

先创建一个简单的 JS 项目：

mkdir math-lib
cd math-lib
git init

手动创建 math.js 文件：

// math.js
function add(a, b) { return a + b; }
function subtract(a, b) { return a - b; }
function multiply(a, b) { return a * b; }
function divide(a, b) {
  if (b === 0) throw new Error("除数不能为 0");
  return a / b;
}
function factorial(n) {
  if (n < 0) throw new Error("负数没有阶乘");
  if (n === 0 || n === 1) return 1;
  return n * factorial(n - 1);
}
function fibonacci(n) {
  if (n < 0) throw new Error("负数没有斐波那契数");
  if (n === 0) return 0;
  if (n === 1) return 1;
  return fibonacci(n - 1) + fibonacci(n - 2);
}
module.exports = { add, subtract, multiply, divide, factorial, fibonacci };

提交初始代码：

git add math.js && git commit -m "init: math utility library"

第二步：启动 Aider 并下达测试任务

aider --model claude-3-7-sonnet-20250219

在 Aider 中输入：

> 为 math.js 创建完整的单元测试。使用 Jest 测试框架。要求：
1. 安装 jest 作为 devDependency
2. 创建 __tests__/math.test.js
3. 覆盖以下测试用例：
   - add: 正数相加、负数相加、小数相加
   - subtract: 正数相减、结果为负数的情况
   - multiply: 正数相乘、乘以 0
   - divide: 正常除法、除以 0 抛出异常
   - factorial: 0 的阶乘、正整数的阶乘、负数的异常
   - fibonacci: 第 0 项、第 1 项、第 10 项、负数的异常
4. 添加 npm test 脚本
5. 确保测试全部通过

Aider 会创建 package.json 和 __tests__/math.test.js。

第三步：运行测试验证

退出 Aider，运行测试：

npm test

预期输出：

 PASS  __tests__/math.test.js
  ✓ add function (3 ms)
  ✓ subtract function (1 ms)
  ✓ multiply function (1 ms)
  ✓ divide function (2 ms)
  ✓ factorial function (2 ms)
  ✓ fibonacci function (3 ms)

Tests: 6 passed, 6 total
Time: 0.5 s

如果测试没有全部通过，Aider 会自动检测并尝试修复（如果你开启了 --test 参数）。这个场景充分展示了 Aider 在"已有代码基础上补充测试"任务中的高效表现——从下达指令到全部通过，通常不超过 5 分钟。

第七章 进阶技巧

7.1 优化代码地图大小

对于大型项目，代码地图可能超出 token 限制。优化方式：

• 缩小范围：启动时只加载相关子目录
• 调整 map token 上限：--map-tokens 1024
• 使用 .aiderignore：让 Aider 忽略不需要的文件

# .aiderignore 示例
node_modules/
dist/
build/
*.min.js
*.log

7.2 批量处理多个请求

Aider 支持通过文件或管道批量输入指令：

# 从文件读取指令
aider --message-file instructions.txt

# 从管道输入
echo "将所有的 var 替换为 const/let" | aider --stdin

# 直接传递单条指令
aider --message "给所有函数添加类型注解"

7.3 使用不同模型处理不同任务

策略性使用模型可以平衡效果和成本：

• 复杂重构/架构设计 → Claude 3.7 Sonnet 或 GPT-4o（最强但较贵）
• 日常编码/修 bug → DeepSeek Chat V3 或 GPT-4o-mini（性价比高）
• 简单格式化/批量替换 → 本地模型如 Ollama 上的 Llama 3（免费）

切换模型：

# 在会话中切换模型
> /model claude-3-5-haiku-20241022

# 启动时直接指定
aider --model deepseek-chat

7.4 安全确认模式

如果你希望对每次 AI 修改都进行人工确认，可以使用 --dry-run 预览模式：

# 先预览 AI 计划修改的内容（不实际写入文件）
aider --dry-run --message "给所有函数添加日志"

审查完毕后，去掉 --dry-run 实际执行。

7.5 结合 Web 聊天使用

Aider 支持与 ChatGPT 或 Claude Web 版协同工作：

1. 在 Aider 中使用 /copy 命令复制对话和代码上下文
2. 粘贴到 ChatGPT/Claude Web 中获得更深入的分析
3. 将回答复制回来，Aider 自动识别并应用其中的代码修改

7.6 加速大型项目的技巧

• --cache-prompts：缓存系统提示词，减少 API 调用
• --stream：流式输出，实时显示 AI 响应
• --timeout 120：避免大文件处理时连接超时
• 轻量级 linter：用 ruff 替代 flake8 提升检查速度

第八章 总结与建议

全文总结和最佳实践。

8.1 什么时候该用 Aider？

Aider 在以下场景中表现尤其出色：

• 快速原型开发 — 从零开始创建项目，几分钟搭好骨架
• 补全测试 — 为已有代码生成全面的单元测试
• 代码重构 — 重命名变量、提取函数、优化结构
• 添加新功能 — 在已有代码库中增加功能模块
• 学习新技术 — 用自然语言描述需求，让 Aider 生成示例代码
• 代码审查辅助 — 让 AI 先过一遍代码，发现潜在问题

8.2 什么时候需要谨慎？

• 安全敏感场景 — AI 生成的代码可能存在安全漏洞，密码学、认证等需要人工审查
• 高度优化的性能代码 — AI 可能不了解底层硬件特性和调优技巧
• 遗留系统维护 — 非常老旧的代码库可能不在 AI 训练数据中

8.3 最佳实践

• 小步提交 — 每次赋予 Aider 一个小而明确的任务，而非大而模糊的需求
• 审查每次提交 — 使用 git show 查看每次 AI 提交的改动
• 善用 .aiderignore — 让 Aider 专注于代码文件，忽略生成的文件
• 保持代码风格一致 — 在配置中指定 linter 规则，引导一致的输出风格
• 先设计后编码 — 先和 Aider 讨论设计方案，再让它动手写代码
• 定期更新 — pip install -U aider-install 获取最新功能

8.4 下一步

• 官方文档：aider.chat 包含完整的用户指南和 API 参考
• GitHub 仓库：github.com/Aider-AI/aider 关注最新 Release
• 进阶方向：探索自定义编辑格式、构建自定义 .aider.conf.yml、尝试本地 LLM

第九章 常见问题 FAQ

9.1 问题一：如何将 GitHub Copilot 添加为 Aider 的模型提供商？

问题描述： 社区用户希望将 GitHub Copilot 作为 Aider 的模型提供商。GitHub Copilot 底层基于 OpenAI 模型，但 Aider 目前未将其列为官方支持的提供商。该功能请求在 GitHub 上有 212 条讨论。

原因分析： GitHub Copilot 的 API 使用自定义认证和请求格式，不是标准的 OpenAI 兼容 API。同时 Copilot 的使用条款也限制了其作为通用 AI 编程助手的调用方式。

解决步骤：

1. 推荐变通：直接使用 OpenAI API Key。如果你有 GitHub Copilot 订阅，可额外申请 OpenAI API Key，在 Aider 中设置 OPENAI_API_KEY 即可
2. 自定义端点：通过 --model 参数指定自定义 OpenAI 兼容端点，但需确认 Copilot API 的兼容性
3. 关注进展：该功能请求标记为 open，关注 GitHub Issues 获取最新动态

9.2 问题二：Aider 是否支持其他 LLM 或本地 LLM？

问题描述： 用户想知道 Aider 除了 OpenAI 外，是否支持其他 LLM，尤其是本地模型。该汇总性问题有 133 条讨论。

原因分析： Aider 通过 litellm 库已支持大量 LLM 提供商，但许多用户不清楚具体支持列表和本地模型配置方法。

解决步骤：

1. 云模型：支持 OpenAI、Anthropic、DeepSeek、Google Gemini、Groq、OpenRouter 等，设置对应环境变量即可
2. 本地模型：通过 Ollama 运行：
   复制

   ollama pull codestral
   aider --model ollama/codestral

3. OpenRouter 统一入口：一个 API Key 访问多种模型
4. 官方文档：完整列表参考 aider.chat/docs/llms.html

9.3 问题三：Aider 报错 "OpenrouterException - 'choices'" 怎么办？

问题描述： 使用 Aider 搭配 OpenRouter 时出现以下错误，52 条讨论，已关闭。

litellm.APIConnectionError: APIConnectionError: OpenrouterException - 'choices'
Retrying in...

原因分析： OpenRouter 返回的 JSON 结构中缺少 choices 字段，通常由于后端模型超时、API 版本不兼容、账户余额不足或限流导致。

解决步骤：

1. 登录 openrouter.ai 检查账户余额
2. 升级 litellm：pip install -U litellm
3. 临时切换到其他模型或直接使用 Anthropic API
4. 增加重试：aider --retry 3
5. 检查网络连接是否稳定

9.4 问题四：Aider 和 Claude Code 有什么关系？

问题描述： Anthropic 发布了官方 Claude Code CLI 工具，用户想知道两者区别，48 条讨论。

原因分析： Claude Code 是 Anthropic 官方终端 AI 编程工具，与 Aider 功能定位类似但设计理念不同。

解决步骤：

1. 核心区别：Claude Code 仅支持 Claude 模型；Aider 是开源社区项目，支持数十种 LLM
2. 选择建议：主要用 Claude 可选 Claude Code；需要多模型灵活切换或偏好开源选 Aider；两者可互补使用
3. 社区生态：Aider 有 aidermacs、VS Code 扩展等多元化第三方集成

9.5 问题五：DeepSeek API 超时或无响应怎么办？

问题描述： DeepSeek 经常出现 API 无响应、超时或极慢的问题，40 条讨论，已关闭。

原因分析： DeepSeek API 曾经历严重服务故障，免费 API 在高峰时段负载过大导致不稳定。并非 Aider 本身问题。

解决步骤：

1. 访问 status.deepseek.com 查看官方服务状态
2. 增加超时时间：aider --timeout 300
3. 临时切换到其他提供商如 Groq 的 Llama 3 或 OpenAI GPT-4o-mini
4. 配置本地模型作为 fallback：aider --model ollama/llama3
5. 通过 OpenRouter 配置故障转移，DeepSeek 不可用时自动切换

9.6 问题六：如何让 Aider 在每次修改前先请求用户确认？

问题描述： 用户希望在 Aider 应用修改前逐一确认每次原子修改，39 条讨论。

原因分析： Aider 默认设计理念是"信任 AI 自动生成代码，依靠 Git 回滚作为安全网"。当前版本没有内置"修改前确认"交互模式。

解决步骤：

1. --dry-run 预览：只显示计划修改内容不实际写入，审查后再执行：
   复制

   aider --dry-run --message "给所有函数添加日志"

2. Git 事后审查：每次自动提交后用 git show 查看 diff，不满意用 git reset HEAD~1 --hard 回滚
3. 关闭自动提交：aider --no-auto-commits --no-auto-add，手动审查后用 git diff 确认无误再提交
4. 关注进展：该功能请求在 GitHub 上标记为 open，正在评估中

💡 从安全角度考虑，Aider 的每次修改都是原子化 Git 提交，配合 git show 和 git reset，实际上已实现"先审查后确认"的工作流——只是在修改之后而不是之前确认。对于大多数开发者，事后审查效率高于事前逐条确认。

附录：命令速查表

安装与更新

基本使用

配置参数

环境变量

对话内斜杠命令

实用快捷操作