Aider 安装、使用方法详细全解

Aider 安装、使用方法详细全解

数据来源：GitHub 仓库、aider.chat 官方文档

---

一、项目概况

1.1 基本信息

项目	详情
名称	Aider (AI Pair Programming in Your Terminal)
仓库	https://github.com/Aider-AI/aider
文档	https://aider.chat/docs/
开源协议	开源免费
社区	Discord: https://discord.gg/Y7X7bhMQFV

1.2 核心定位

Aider 是一个运行在终端中的 AI 结对编程工具。它与 LLM 对话，直接编辑你本地 Git 仓库中的代码文件，并自动提交每一次变更。它不是编辑器插件，而是一个独立的 CLI 工具，设计理念是"小而快、厂商中立"，可以在任何 shell 中使用（SSH、tmux、远程服务器等）。

1.3 核心特性

1. 多云和本地 LLM 支持 --- 连接几乎所有 LLM，包括云端和本地模型
2. 代码仓库映射 (Repo Map) --- 自动为整个代码库生成结构映射，使 AI 能在大型项目中工作
3. 100+ 编程语言 --- 支持 Python、JavaScript、Rust、Ruby、Go、C++、PHP、HTML、CSS 等
4. Git 深度集成 --- 自动提交、自动生成提交信息、支持 undo/redo
5. IDE 集成 --- 通过 Watch 模式在 IDE 中通过代码注释驱动 AI 修改
6. 图片与网页支持 --- 在对话中添加截图、网页链接作为上下文
7. 语音编码 (Voice-to-code) --- 语音输入编程需求
8. 自动 Lint 和测试 --- 变更后自动运行 lint/test，AI 自动修复问题
9. Web 聊天复制粘贴 --- 与任何 LLM Web 界面配合使用

---

二、安装方法

2.1 推荐方式：aider-install（一键安装）

前提：已安装 Python 3.8-3.13

# 第一步：安装辅助工具
python -m pip install aider-install

# 第二步：一键安装 aider
aider-install

这会在独立的 Python 环境中安装 aider。如果需要，aider-install 还会自动安装独立的 Python 3.12。

2.2 一行命令安装（基于 uv）

Mac/Linux（使用 curl）：

curl -LsSf https://aider.chat/install.sh | sh

Mac/Linux（使用 wget）：

wget -qO- https://aider.chat/install.sh | sh

Windows：

powershell -ExecutionPolicy ByPass -c "irm https://aider.chat/install.ps1 | iex"

2.3 使用 uv 安装

# 安装 uv（如尚未安装）
python -m pip install uv

# 安装 aider
uv tool install --force --python python3.12 --with pip aider-chat@latest

这会使用现有的 Python 3.8-3.13 安装 uv，如果需要会自动安装独立的 Python 3.12。

2.4 使用 pipx 安装

# 安装 pipx（如尚未安装）
python -m pip install pipx

# 安装 aider
pipx install aider-chat

支持 Python 3.9-3.12。

2.5 使用 pip 直接安装

python -m pip install -U --upgrade-strategy only-if-needed aider-chat

建议搭配虚拟环境使用。如果遇到 "aider command not found" 错误，可尝试 python -m aider。

2.6 其他方式

• Docker --- 官方提供 Docker 镜像
• GitHub Codespaces --- 支持在 Codespaces 中运行
• Replit --- 支持在 Replit 环境运行
• 系统包管理器 --- 虽然可用但不推荐，依赖可能不正确

2.7 版本检查与更新

aider --version
python -m pip install -U aider-chat

---

三、使用方法（全面详解）

3.1 快速开始

# 进入你的项目目录
cd /to/your/project

# 使用 DeepSeek 模型
aider --model deepseek --api-key deepseek=<key>

# 使用 Claude 3.7 Sonnet
aider --model sonnet --api-key anthropic=<key>

# 使用 OpenAI o3-mini
aider --model o3-mini --api-key openai=<key>

启动后进入交互式聊天界面：

$ aider factorial.py

Aider v0.37.1-dev
Models: gpt-4o with diff edit format, weak model gpt-3.5-turbo
Git repo: .git with 258 files
Repo-map: using 1024 tokens
Use /help to see in-chat commands, run with --help to see cmd line args
───────────────────────────────────────────────────────────────────────
>

3.2 文件管理

添加文件到对话（可编辑）：

• 启动时直接指定：aider file1.py file2.js
• 对话中使用 /add 命令：/add file1.py file2.js

只读文件（参考用）：

• /read-only file.py --- 添加仅用于参考的文件

移除文件：

• /drop file.py --- 从对话中移除文件

列出所有文件：

• /ls --- 列出所有已知文件及是否在对话中

重要原则：

• 只添加需要编辑的文件，不要添加过多文件
• Aider 通过 Repo Map 自动获取相关上下文，不需要手动添加所有相关文件
• 可以不加任何文件启动，Aider 会根据你的请求自动判断需要编辑哪些文件

3.3 API Key 配置

有 4 种等效方式设置 API Key：

方式 1：命令行参数

aider --openai-api-key sk-xxx
aider --anthropic-api-key sk-ant-xxx
aider --api-key provider=key  # 其他提供商

方式 2：环境变量

export OPENAI_API_KEY=sk-xxx
export ANTHROPIC_API_KEY=sk-ant-xxx
export DEEPSEEK_API_KEY=sk-xxx

方式 3：.env 文件（放在项目根目录）

OPENAI_API_KEY=sk-xxx
ANTHROPIC_API_KEY=sk-ant-xxx

方式 4：YAML 配置文件 （.aider.conf.yml）

openai-api-key: sk-xxx
anthropic-api-key: sk-ant-xxx

配置文件位置：~/.aider.conf.yml（全局）或项目根目录 ./.aider.conf.yml（项目级）。

3.4 支持的最佳模型

Aider 与以下模型配合效果最佳：

• Gemini 2.5 Pro
• DeepSeek R1 和 V3
• Claude 3.7 Sonnet
• OpenAI o3、o4-mini 和 GPT-4.1

免费模型选项：

• OpenRouter 提供免费模型访问（有日用限制）
• Google Gemini 2.5 Pro Exp

本地模型：

• 通过 Ollama 使用本地模型
• 支持任何提供 OpenAI 兼容 API 的本地模型

3.5 支持的所有 LLM 提供商

OpenAI、Anthropic、Gemini、GROQ、LM Studio、xAI、Azure、Cohere、DeepSeek、Ollama、OpenAI 兼容 API、OpenRouter、GitHub Copilot、Vertex AI、Amazon Bedrock 等。

3.6 聊天模式（Chat Modes）

Aider 有 4 种聊天模式，可在对话中随时切换：

1. Code 模式（默认）

• 可以编辑文件
• 启动时默认模式
• 切换命令：/code 或 /chat-mode code

2. Ask 模式

• 只回答关于代码库的问题，不编辑文件
• 切换命令：/ask 或 /chat-mode ask

3. Architect 模式

• 使用两个不同的模型：一个用于架构决策，一个用于编辑代码
• 切换命令：/architect 或 /chat-mode architect

4. Context 模式

• 查看代码上下文，帮助理解代码
• 切换命令：/context 或 /chat-mode context

推荐工作流：Ask/Code 交替

> /ask 如何重构这个认证模块？
[讨论方案，获取建议...]
> /code 好的，按第一个方案执行
[执行代码修改...]
> /code 再把日志级别改成 debug
[继续修改...]

在 ask 模式中充分讨论方案，然后切换到 code 模式执行。只需说"go ahead"即可让 Aider 基于讨论内容执行修改。

启动时指定模式：

aider --ask          # 启动进入 ask 模式
aider --code         # 启动进入 code 模式（默认）

3.7 完整的 Slash 命令参考

文件管理命令

命令	说明
/add [文件]	添加文件到对话，使 aider 可以编辑或详细审查
/drop [文件]	从对话中移除文件，释放上下文空间
/read-only [文件]	添加仅用于参考的文件（不编辑）
/ls	列出所有已知文件，标记哪些在对话中
/reset	移除所有文件并清除聊天历史

模型相关命令

命令	说明
/model [模型名]	切换主模型
/models [搜索词]	搜索可用模型列表
/weak-model [模型名]	切换弱模型（用于 commit message 等轻量任务）
/editor-model [模型名]	切换编辑器模型（architect 模式下的编辑模型）
/model	不带参数时显示当前模型

聊天模式命令

命令	说明
/code [提示]	请求代码修改；不带参数切换到 code 模式
/ask [问题]	询问代码库问题，不编辑文件；不带参数切换到 ask 模式
/architect [提示]	进入 architect/editor 模式（双模型）
/context [提示]	进入 context 模式查看代码上下文
/chat-mode [模式名]	切换到指定聊天模式
/clear	清除聊天历史
/ok	别名：好的，请继续执行上述变更

执行与测试命令

命令	说明
/run [命令]	运行 shell 命令，可选择将输出添加到对话（别名：!）
/test [命令]	运行 shell 命令，非零退出码时将输出添加到对话
/lint	对对话中文件（或所有脏文件）运行 lint 并自动修复
/git [命令]	运行 git 命令（输出不包含在对话中）

Git 相关命令

命令	说明
/commit [消息]	提交对话外的编辑（可选提交消息）
/undo	撤销上一次由 aider 执行的 git commit
/diff	显示自上次消息以来的变更 diff

上下文管理命令

命令	说明
/map	打印当前仓库映射
/map-refresh	强制刷新仓库映射
/tokens	报告当前对话上下文的 token 使用量
/think-tokens [数量]	设置思考 token 预算（如 8096, 8k, 10.5k, 0.5M, 0 禁用）
/reasoning-effort [级别]	设置推理努力级别（low/medium/high 或数字）

输入与输出命令

命令	说明
/editor	打开编辑器编写提示（别名：/edit）
/voice	录制并转录语音输入
/paste [名称]	从剪贴板粘贴图片/文本到对话
/copy	复制最后一条助手消息到剪贴板
/copy-context	复制当前聊天上下文为 markdown，适合粘贴到 Web UI
/web [URL]	抓取网页，转换为 markdown 并作为消息发送
/multiline-mode	切换多行模式（交换 Enter 和 Meta+Enter 的行为）

会话管理命令

命令	说明
/save [文件]	保存可重建当前会话的命令到文件
/load [文件]	从文件加载并执行命令
/settings	打印当前设置
/help [问题]	询问关于 aider 的使用问题
/report	通过创建 GitHub Issue 报告问题
/exit / /quit	退出应用

3.8 Git 集成详解

自动提交：

• Aider 每次修改代码后自动创建 git commit
• 自动生成符合 Conventional Commits 规范的提交信息
• 提交信息由弱模型（默认 gpt-3.5-turbo）基于 diff 和对话历史生成

提交标记：

• Co-Authored-By: aider --- 如果 aider 撰写了变更
• Committed-By: aider --- 如果 aider 执行了提交

手动 Git 操作：

• /git status --- 查看状态
• /git log --- 查看历史
• /undo --- 撤销上一次 aider 的 commit
• /commit "自定义消息" --- 提交对话外的编辑

禁用 Git 集成（不推荐）：

aider --no-git          # 不初始化/使用 git
aider --no-auto-commit  # 不自动提交

3.9 仓库映射（Repo Map）

Aider 自动生成整个 Git 仓库的结构映射，帮助 LLM 理解大型项目：

• 自动扫描仓库中所有跟踪的文件
• 提取类、函数、方法等符号定义
• 将映射信息注入上下文，使 AI 了解"不在对话中的文件"
• 使用 /map 查看当前映射
• 使用 /map-refresh 强制刷新
• 默认使用 1024 tokens 存储映射

意义： 你不需要把所有相关文件都加到对话中。Aider 通过 Repo Map 已经知道项目结构，会自动 pull in 相关代码的上下文。

3.10 IDE 集成（Watch 模式）

启动 Watch 模式：

aider --watch

工作原理：

• Aider 监控仓库中所有文件
• 在代码中添加特殊注释来向 AI 发出指令
• 支持三种注释触发器：
  • AI! --- 触发 AI 收集并执行所有 AI 注释
  • AI? --- 触发 AI 回答问题（不修改代码）
  • AI --- 普通标记，不触发

示例：

# Python
def sqrt(x):
    # Add error handling for negative numbers. AI!
    return x ** 0.5

// JavaScript
app.get('/sqrt/:n', (req, res) => {
    // Add error handling for NaN and less than zero. AI!
    const result = math.sqrt(n);
    res.json({ result: result });
});

支持的语言注释类型：

• # AI! --- Python、Ruby 等
• // AI! --- JavaScript、Go、Rust、Java 等
• * AI! --- C、Objective-C 等
• -- AI! --- SQL、Lua 等
• ;%20AI! --- INI 等

使用场景：

1. 上下文指令 --- 在需要修改的函数旁边直接写注释
2. 多注释 --- 添加多个 AI 注释（无感叹号），最后用一个 AI! 触发
3. 跨文件 --- 可以在多个文件中分散添加 AI 注释，统一触发
4. 与 IDE 配合 --- 在 VSCode/PyCharm 等编辑器中写代码，在终端后台运行 aider --watch

3.11 Lint 和测试集成

自动 Lint 和测试：

# 设置 lint 命令
aider --lint-command "flake8 ."

# 设置测试命令
aider --auto-test "pytest -x tests/"

手动执行：

> /lint              # 运行 lint 并自动修复
> /test pytest -x    # 运行测试，失败时自动分享错误
> /run make test     # 运行命令并分享输出

工作流程：Aider 修改代码后自动运行 lint/test → 检测问题 → AI 自动修复 → 重新验证。

3.12 图片与网页

添加图片：

> /paste             # 从剪贴板粘贴图片
> screenshot.png     # 直接添加图片文件

添加网页：

> /web https://docs.python.org/3/library/os.html
# 或直接在消息中包含 URL

3.13 语音编码

> /voice
# 按住说话，录制后自动转录为文本

3.14 编码规范

创建 .aider.conventions 文件指定编码规范：

# .aider.conventions
# 编码规范
- 使用类型注解
- 遵循 PEP 8
- 函数需要 docstring

或使用 --coderules 命令行参数指定。

3.15 提示词缓存

支持 Anthropic 和 OpenAI 的 prompt caching 功能，减少重复 token 费用。在配置文件或环境变量中启用。

3.16 通知

支持系统通知，当 AI 完成长时间操作时通知用户。

3.17 浏览器模式

支持在浏览器中与 Aider 交互，适合没有终端环境的场景。

---

四、配置选项

4.1 配置文件

配置文件名：.aider.conf.yml

位置：~/.aider.conf.yml（全局）或项目根目录 ./.aider.conf.yml（项目级）

示例配置：

dark-mode: true
model: sonnet
anthropic-api-key: sk-ant-xxx
openai-api-key: sk-xxx
lint-command: flake8 .
auto-test: pytest -x tests/

4.2 环境变量

export AIDER_DARK_MODE=true
export AIDER_MODEL=sonnet
export OPENAI_API_KEY=sk-xxx

4.3 命令行参数

所有配置选项均可通过命令行设置：

aider --model sonnet --dark-mode --lint-command "flake8 ."

查看完整参数：aider --help

4.4 常用配置选项

配置项	说明
model	主模型
weak-model	弱模型（commit message 等）
editor-model	编辑器模型（architect 模式）
dark-mode	深色模式终端输出
lint-command	Lint 命令
auto-test	自动测试命令
repo-map	仓库映射开关
yes-always	自动确认所有操作
verbose	详细输出
no-git	禁用 Git 集成
no-auto-commit	禁用自动提交
add-gitignore-files	允许编辑 .gitignore 中的文件

4.5 模型别名

可以为常用模型创建别名，简化命令：

# .aider.conf.yml
model-aliases:
  my-sonnet: anthropic/claude-3.7-sonnet
  my-deepseek: deepseek/deepseek-chat

---

五、最佳实践与工作流建议

5.1 基本原则

1. 只添加需要编辑的文件 --- 不要添加多余文件，AI 会被无关代码分散注意力
2. 分步执行 --- 将复杂目标分解为小步骤，逐个完成
3. 先讨论后执行 --- 复杂变更先用 /ask 讨论方案，再 /code 执行
4. 动态调整文件 --- 随着任务进展，用 /add 和 /drop 管理对话中的文件
5. 善用 /run 和 /test --- 将错误输出和测试结果分享给 AI，让它自动修复

5.2 创建新文件

如果希望 Aider 创建新文件，先用 touch 创建空文件：

touch new_module.py
aider new_module.py

这样 Aider 知道该文件存在，会写入该文件而不是修改已有文件。

5.3 卡住时的处理方法

1. 重新描述问题，提供更多上下文
2. /clear 清除历史后重新开始
3. /drop 移除不需要的文件减少干扰
4. /model 切换到更强的模型
5. /help 具体问题 向 Aider 本身寻求帮助

5.4 修复 Bug 和错误

1. 用 /run 运行出错的命令，将错误输出分享给 Aider
2. 或者直接粘贴错误信息到聊天
3. 如果测试失败，用 /test 运行测试
4. 让 Aider 自己分析和修复

5.5 提供文档

LLM 可能不了解特定库的最新 API：

• 在消息中包含文档 URL，Aider 会自动抓取
• 使用 /read 添加文档文件
• 使用 .aider.conventions 指定项目约定

---

六、高级用法

6.1 Architect 模式（双模型）

使用两个模型协同工作：

• 架构师模型 --- 理解需求、做决策（通常用更强的模型）
• 编辑模型 --- 执行具体代码修改（可以用更快的模型）

aider --architect --model sonnet --editor-model gpt-4o
# 或在对话中切换
> /architect

6.2 脚本化 Aider

Aider 可以通过命令行参数执行单次任务并退出：

aider --no-git --message "解释这个代码" script.py

6.3 成本优化

• 使用弱模型（--weak-model）处理 commit message 等轻量任务
• 使用 /tokens 监控 token 消耗
• 只添加必要的文件到对话
• 使用 prompt caching（Anthropic/OpenAI 支持）
• 选择性价比高的模型（如 DeepSeek V3 性价比极高）

6.4 非 Git 项目

aider --no-git file1.py file2.py

可以正常使用，但缺少自动提交、diff 管理等优势。

---

七、与其他工具的对比

特性	Aider	Cursor	Claude Code	Windsurf
运行方式	CLI 终端	VS Code 分叉	CLI 终端	VS Code 分叉
Git 集成	深度原生	一般	有	一般
模型选择	几乎所有 LLM	有限	Anthropic	有限
远程服务器	优秀	不支持	好	不支持
开源	是	否	部分	否
IDE 集成	Watch 模式	本身就是 IDE	独立	本身就是 IDE
价格	免费开源	订阅制	按用量	订阅制

---

八、常见问题

Q: 需要 Python 什么版本？

A: Python 3.8-3.13。推荐 Python 3.12。

Q: 必须用 Git 吗？

A: 不是必须，但强烈推荐。Aider 的设计深度依赖 Git。

Q: 可以在非 Git 仓库中使用吗？

A: 可以，使用 --no-git 参数。

Q: 支持哪些编辑器/IDE？

A: Aider 是独立 CLI 工具，通过 Watch 模式与任何 IDE 配合使用。

Q: 如何撤销 AI 的修改？

A: 在对话中 /undo，或使用 git revert / git reset。

Q: 并发使用多个 Aider 实例安全吗？

A: 不建议在同一 Git 仓库中同时运行多个 Aider 实例。

---

九、总结

Aider 是目前最成熟的开源终端 AI 结对编程工具之一，核心优势在于：

1. Git 原生设计 --- 每次变更自动提交，可追溯、可撤销
2. 模型无关 --- 支持几乎所有主流 LLM，用户可以自由切换
3. 终端优先 --- 可以在任何环境中使用，包括远程 SSH 服务器
4. Repo Map 技术 --- 自动理解大型代码库结构
5. Watch 模式 --- 与任何 IDE 无缝配合
6. 完全开源免费 --- 只需支付 LLM API 费用

最适合的用户群体：

• 需要在远程服务器/容器中编码的开发者
• 喜欢终端工作流的开发者
• 希望自由选择 LLM 提供商的用户
• 对 Git 工作流有严格要求的团队
• 寻找 Cursor/Claude Code 免费替代方案的用户

---