Aider终端AI结对编程完全指南：2026零基础教程

TL;DR

Aider 是一款开源、基于终端的 AI 结对编程工具，它直接在你的本地 Git 仓库中编辑代码。你用自然语言和它聊天，它通过 repo-map 理解你的整个代码库，进行多文件编辑，并为每一次修改创建原子化的 Git 提交。它支持 Claude Sonnet、GPT-5、DeepSeek V4 以及通过 Ollama 运行的本地模型——你完全不会被任何厂商锁定。本指南涵盖安装、多模型配置、核心工作流、架构师/编辑器模式，以及让你在 30 分钟内高效上手的最佳实践。

前置条件

开始之前，请确保你具备以下条件：

• 系统已安装 Python 3.10+（python3 --version 确认版本）
• 已安装并配置 Git（git --version 确认）
• 已安装 pipx 用于隔离安装 Python 工具（pip install pipx && pipx ensurepath）
• 至少一个 LLM 提供商的 API Key（OpenAI、Anthropic、DeepSeek 或通过 Ollama 的本地模型）
• 一个可以工作的 Git 仓库——Aider 在已有仓库中运行最佳（它会自动提交，所以保持 Git 状态干净很重要）

第一步：安装 Aider

推荐通过 pipx 安装 Aider，它会将 Aider 放在隔离的环境中，不会和你其他的 Python 项目产生冲突。

# 如果你还没有 pipx，先安装它
python3 -m pip install --user pipx
python3 -m pipx ensurepath

# 安装 Aider
pipx install aider-chat

安装完成后，验证是否正常工作：

aider --version

# 预期输出：aider v0.80.x（或类似版本号）

其他安装方式：

• pip（不推荐）： pip install aider-chat——可能与其他 Python 包冲突
• Docker： docker pull paulgauthier/aider——适合 CI/CD 或不想在本机装 Python 的场景
• 一键安装脚本： 在 aider.chat/docs/install.html 可获取 macOS/Linux 安装脚本

第二步：设置 API Key

Aider 需要一个 API Key 来与 LLM 通信。你可以使用任何支持的提供商。以下是最常见的几种：

方案 A：Anthropic Claude（推荐，效果最佳）

Claude Sonnet 4 在 Aider 中持续产出最佳的代码质量。

# macOS/Linux
export ANTHROPIC_API_KEY="sk-ant-..."

# 添加到 shell 配置文件以持久化
echo 'export ANTHROPIC_API_KEY=*** >> ~/.zshrc

然后启动：

aider --model sonnet

方案 B：OpenAI（GPT-5）

export OPENAI_API_KEY="sk-..."
aider --model openai/gpt-5

# 或者选择更便宜的方案：
aider --model openai/gpt-5-mini

方案 C：DeepSeek V4（最便宜，开源）

export DEEPSEEK_API_KEY="sk-..."
aider --model deepseek/deepseek-chat

方案 D：通过 Ollama 使用本地模型（免费，隐私）

# 安装 Ollama 并拉取模型
ollama pull qwen3:32b

# 用本地模型启动 Aider
aider --model ollama/qwen3:32b

小贴士： 你可以在 ~/.aider.conf.yml 中设置默认模型，这样每次启动就不需要手动传 --model 参数。

第三步：你的第一次 Aider 会话

进入一个 Git 项目目录并启动 Aider：

cd ~/projects/my-app
aider

Aider 会在聊天模式下启动。你会看到类似这样的界面：

Aider v0.80.0
Model: claude-sonnet-4-20250514
Git repo: .git with 24 files
Repo-map: using 1024 tokens, auto-refresh
────────────────────────────────────────────────
>

核心命令

Aider 有几个你会频繁使用的基础斜杠命令：

实操示例：给 React 应用添加暗黑模式

让我们走一遍真实的工作流程。假设你有一个 React 应用，想要添加暗黑模式支持：

> /add src/App.tsx src/index.css src/components/ThemeToggle.tsx
已添加 3 个文件到聊天会话。

> 使用 React Context 添加暗黑模式切换功能。创建一个 ThemeContext、
  一个包裹整个应用的 ThemeProvider，以及一个 ThemeToggle 按钮组件。
  使用 Tailwind CSS 的 dark: 类。将用户偏好存储在 localStorage 中。

Aider 将会：

1. 读取你添加的文件
2. 利用 repo-map 理解代码结构，规划修改方案
3. 创建/编辑文件
4. 运行必要的安装命令（如 npm install）
5. 为每个逻辑修改自动提交，附带描述性的提交信息

你会看到类似这样的输出：

已添加 src/contexts/ThemeContext.tsx
已编辑 src/App.tsx
已编辑 src/index.css
已创建 src/components/ThemeToggle.tsx

正在提交：feat: 添加暗黑模式，支持 ThemeContext 和 localStorage 持久化

第四步：理解 Repo-Map

Aider 的核心杀手锏之一是 repo-map——一个自动生成的代码库高层索引，帮助 LLM 理解你的项目结构。

repo-map 使用 Tree-sitter 解析你的代码并提取：

• 所有函数和类的签名
• 类型定义
• 导入/导出关系
• 文件结构和层级

这意味着你不需要手动添加每个文件。Aider 已经知道有哪些函数、它们的名称以及它们之间的关系。当你说「更新 authenticate 函数以支持 OAuth」时，Aider 会搜索 repo-map，找到该函数并编辑它——即使你从未显式添加过那个文件。

你可以查看 repo-map 消耗了多少 tokens：

aider --map-tokens 2048   # 增加 repo-map 上下文（默认：1024）
aider --no-map-tokens      # 禁用 repo-map（不推荐）

第五步：架构师/编辑器模式（进阶）

对于复杂的多文件修改，Aider 提供了架构师/编辑器模式——一种双模型工作流程：

1. 架构师模型（侧重推理，如 Claude Opus 或 o3）分析问题并生成详细方案
2. 编辑器模型（侧重代码生成，如 Claude Sonnet 或 DeepSeek V4）执行方案

这种「思考」与「执行」的分离显著提升复杂重构的效果。架构师一次性处理困难的推理，编辑器则专注于实现。

# 用 o3 做架构师，Sonnet 做编辑器
aider --architect --model openai/o3 --editor-model sonnet

# 用 DeepSeek R1 做架构师，DeepSeek V4 做编辑器
aider --architect --model deepseek/deepseek-reasoner --editor-model deepseek/deepseek-chat

何时使用架构师模式：

• 涉及 5 个以上文件的大型重构
• 数据库 schema 迁移
• API 重新设计（REST 转 GraphQL）
• 添加新的架构层（认证、缓存、事件系统）

何时跳过（使用普通 /code）：

• 单文件 Bug 修复
• 添加简单功能（一个组件、一个路由）
• 更新文档
• 小的格式/样式修改

第六步：Git 集成深度解析

Aider 的 Git 集成不是事后才加的功能——它是工具运作的核心。Aider 所做的每一次修改都会被自动提交，并附带描述性的提交信息。

自动 Git 工作流

1. 当你启动 Aider 时，它会检查是否存在未提交的更改
2. 如果有预先存在的更改，Aider 会先提交它们（以便将其编辑隔离开来）
3. 每个产生文件修改的 /code 请求都会触发一次原子提交
4. 提交信息描述了改了什么以及为什么改

安全特性

# Aider 会自动为自己创建 gitignore 条目

# 以避免提交自己的缓存文件

# 撤销 Aider 的最后一次提交
> /undo

# 查看修改了什么
> /diff

# 显式提交（很少需要——通常是自动的）
> /commit

分支工作流

# 在做大改动前创建功能分支
git checkout -b feature/add-auth

# 在该分支中启动 Aider
aider

# Aider 的提交都留在这个分支上

# 你可以在之后 review、squash 或 rebase

最佳实践： 使用 Aider 做非琐碎修改时，始终在功能分支上工作。这给你提供了一条干净的撤回路径，也让 PR review 更容易。

第七步：多文件编辑与上下文管理

Aider 可以在一次请求中编辑多个文件——但你需要明智地管理上下文。

添加文件

# 添加特定文件
> /add src/auth.ts src/db.ts src/api/routes.ts

# 添加目录中的所有文件
> /add src/components/*.tsx

# 使用只读文件（Aider 可以看到但不会编辑）
> /read docs/API_SPEC.md

上下文限制

每个 LLM 都有上下文窗口限制。Aider 会显示你正在使用多少上下文：

如果你正在接近限制：

• 使用 /drop <文件> 将文件从上下文中移除
• 使用 /clear 重置对话（repo-map 保留）
• 只添加 Aider 真正需要看到的文件——而不是整个项目

聊天内创建文件

你可以让 Aider 创建新文件而不需要提前添加：

Aider 会创建该文件，将其添加到聊天中，并提交。

第八步：配置与自定义

.aider.conf.yml` 文件

创建 ~/.aider.conf.yml 以持久化设置：

# ~/.aider.conf.yml
model: sonnet
dark-mode: true
map-tokens: 2048
auto-commits: true
git: true
chat-language: Chinese

项目级 `.aider.conf.yml

在你项目的根目录放置一个 .aider.conf.yml 以进行项目特定设置，会覆盖全局配置：

# ./my-project/.aider.conf.yml
model: openai/gpt-5
read: [docs/STYLE_GUIDE.md, docs/ARCHITECTURE.md]
auto-test: true
test-cmd: npm test

常用配置项

第九步：成本管理

Aider 让你对 API 调用花费有清晰的可见性。

跟踪用量

每次会话结束后，Aider 会显示一个摘要：

总费用：$0.42
总 tokens：85,000 提示词 + 12,000 补全
会话时长：12 分钟

省钱技巧

1. 简单编辑用 DeepSeek——DeepSeek V4 的成本仅为 Claude/GPT 的一个零头，能胜任大多数编码任务
2. 充分利用 /clear——聊天历史中的每条消息都会增加提示词 tokens
3. 提示词要具体——模糊的提示词会导致来回修正，成倍增加费用
4. 在配置中设置预算：

# .aider.conf.yml
max-chat-history-tokens: 8000  # 限制累积的上下文

模型成本对比（2026 年 6 月，近似值）

第十步：进阶工作流

Lint-修复循环

# 设置自动 lint
aider --lint-cmd "eslint --fix src/" --auto-lint

# Aider 会在每次修改后运行 linter 并自动修复问题

用 Aider 做测试驱动开发

# 先写一个失败的测试，然后让 Aider 使其通过
> /add tests/test_auth.py

> 测试 `test_login_returns_jwt` 正在失败。实现 src/auth.py 中的
  login 端点使其通过。使用 JWT 和 HS256 算法。

PR Review 工作流

# 克隆 PR 分支
git fetch origin pull/42/head:pr-42
git checkout pr-42

# 让 Aider 进行 Review
aider --message "Review 这个 PR。检查安全问题、缺少的错误处理，并提出改进建议。输出结构化的 Review 意见。"

多仓库协调

# 使用 /read 从外部仓库引入文件
> /read ../shared-library/src/types.ts
> /read ../api-docs/openapi.yaml

# 现在 Aider 可以使用来自兄弟项目的类型和 API 规范

常见问题排查

「API key 未找到」

确保你导出了正确的环境变量：

• OpenAI: OPENAI_API_KEY
• Anthropic: ANTHROPIC_API_KEY
• DeepSeek: DEEPSEEK_API_KEY

运行 echo $ANTHROPIC_API_KEY 验证。如果返回空，重新导出。

「Git 仓库未找到」

Aider 需要一个 Git 仓库。初始化一个：

git init
git add .
git commit -m "初始提交"

「Aider 做出了我不喜欢的修改」

# 撤销 Aider 的最后一次提交
> /undo

# 或者手动回退
git log --oneline  # 找到 Aider 的提交
git revert <commit-hash>

「上下文窗口已满」/ 响应变慢

• 使用 /drop 移除不再需要的文件
• 使用 /clear 开启全新对话（repo-map 保留）
• 如果仓库非常大，减少 map-tokens
• 只添加 Aider 真正需要的特定文件，而不是整个项目

「pipx: 命令未找到」

python3 -m pip install --user pipx
python3 -m pipx ensurepath

# 重启终端或运行：
source ~/.zshrc  # 或 ~/.bashrc

相关教程

• Claude Code vs Aider：2026 年 CLI AI 编程代理谁更胜一筹？
• OpenAI Codex CLI 教程：终端优先的 AI 编程代理
• 如何设置 Cursor Rules 进行 AI 编程：完整 .mdc 指南
• n8n AI Agent 教程：构建你的第一个自动化工作流