32 · 常见问题排查
安装失败、登录不上、模型报错、预览白屏、SOLO 卡死——一份从现象到根因的排查手册。
01 排查前的准备工作
在开始逐项排查之前，先掌握两个基本原则。
原则一：先跑诊断
Trae 内置了一个诊断工具，能一次性检查网络、模型、插件兼容性、系统依赖等关键链路：
# 终端中运行
trae --doctor输出示例：
[✓] 网络连接 - 正常 (延迟 45ms)
[✓] 账户认证 - 已登录 (user@example.com)
[✓] 模型接口 - 可用 (模型: claude-sonnet-4-20250514)
[✓] 插件兼容性 - 无冲突
[✓] 系统依赖 - 满足要求
[✓] Git 集成 - 正常如果某一步显示 [x]，说明问题就在那里——直接跳到对应的章节解决。
原则二：日志文件在哪
当 --doctor 看不出来时，日志文件是最直接的信息源：
| 系统 | 日志路径 |
|---|---|
| macOS | ~/Library/Application Support/Trae/logs/ |
| Windows | %APPDATA%\Trae\logs\ |
| Linux | ~/.config/Trae/logs/ |
重点关注 main.log 和 ai-service.log。排查步骤通常就是：
发现异常 → 打开对应日志 → grep ERROR → 看报错堆栈 → 搜索解决方案原则三：安全模式
任何时候遇到扩展导致的崩溃，可以启动安全模式（禁用所有扩展）：
# 命令行启动安全模式
trae --safe
# 或在菜单中：Help → 以安全模式启动02 安装失败
现象
- macOS：.dmg 拖入 Applications 后打不开
- Windows：安装向导中途报错或卡住
- Linux：.AppImage 双击无反应
排查步骤
1. 系统版本不满足要求
Trae 的最低系统要求：
| 系统 | 最低版本 | 检查方法 |
|---|---|---|
| macOS | 11 (Big Sur) | 左上角苹果菜单 → 关于本机 |
| Windows | Windows 10 (build 17763+) | winver |
| Linux | glibc 2.28+ | ldd --version |
如果系统版本过低，升级操作系统是唯一方案。
2. macOS: “无法打开”或”已损坏”
# 如果显示"无法打开，因为 Apple 无法检查其是否包含恶意软件"
sudo spctl --master-disable
# 然后重新打开 Trae
# 或者直接在 Finder 中右键 → 打开（绕过 Gatekeeper）打开 系统设置 → 隐私与安全性，确保允许从 App Store 和被认可的开发者运行。
3. Windows: 安装进度条不动
- 检查杀毒软件是否拦截了安装程序。临时关闭杀毒软件后重试
- 确保有管理员权限：右键安装包 → “以管理员身份运行”
- Windows 11 用户注意：Arm 版 Windows 需要使用 Trae 的 Arm 版本安装包
4. Linux: .AppImage 无法运行
# 首先赋予执行权限
chmod +x trae-*.AppImage
# 如果缺少 FUSE
sudo apt install libfuse2 # Ubuntu/Debian
sudo yum install fuse3 # Fedora/RHEL
# 如果还是无法运行，尝试解压后运行
./trae-*.AppImage --appimage-extract
./squashfs-root/trae5. 磁盘空间不足
Trae 安装后约占用 800 MB - 1.2 GB。确保安装盘有至少 2 GB 可用空间。
安装后的验证
安装完成后的自检清单：
# 1. 验证命令可用
trae --version # 应输出版本号，如 v1.2.3
# 2. 验证诊断通过
trae --doctor # 全部 ✓
# 3. 验证能正常启动
open -a Trae # macOS
trae # Linux / Windows (从终端启动)03 登录问题
这一节是所有问题中排查量最大的。首先确认你装的是哪个版本——这是万恶之源。
3.1 装错了版本
很多人的”登录不上”其实是版本和账号不匹配：
| 你装了 | 你尝试登录的方式 | 结果 |
|---|---|---|
| 国内版 (trae.cn) | Google / GitHub 账号 | ❌ 找不到”用 Google 登录”按钮 |
| 国际版 (trae.ai) | 手机号 | ❌ 没有手机号登录选项 |
| 国内版 | 海外邮箱注册的账号 | ❌ 账号不存在 |
| 国际版 | 抖音扫码 | ❌ 没有这个选项 |
确认方法：看 Trae 窗口的右上角——如果写着”登录”（中文）是国内版，写着”Sign In”是国际版。
解决方案：去对的官网下载对的版本。
- 国内版官网：https://trae.cn
- 国际版官网：https://trae.ai
两个版本可以共存。如果你的工作场景需要同时使用，两个都装，各自独立登录。它们在系统里是两个完全不同的应用。
3.2 国内版登录失败
现象：输入手机号后收不到验证码，或验证码输入后提示”网络错误”。
排查：
- 手机号格式：国内版只支持 +86 手机号。港澳台或海外号码无法使用国内版
- 验证码延迟：高峰期验证码可能有 1-2 分钟延迟。检查手机垃圾短信拦截
- 网络限制：国内版虽然不需要代理，但某些企业内网可能限制了与火山引擎服务的连接。尝试切换 Wi-Fi 或使用手机热点
- 设备限制：免费版账号可在 3 台设备上登录。超出后需要解绑旧设备：
- 打开 Trae → 设置 → 账号 → 已登录设备
- 移除不常用的设备
3.3 国际版登录失败
现象：Google/GitHub OAuth 窗口弹出后白屏、或跳转后没有返回 Trae。
排查：
- OAuth 弹窗被拦截：浏览器的弹窗拦截器可能会阻止 Trae 的 OAuth 窗口。检查系统设置中是否允许 Trae 弹出窗口
- 网络原因（最常见）：国际版需要连接海外服务。如果在中国大陆使用国际版，必须有可用的代理。见 第 06 节 —— 网络与代理问题
- 邮箱验证码未收到：检查垃圾邮件，确认邮箱地址输入正确。Gmail 用户注意邮箱尾缀不要打成
@gamil.com
3.4 登录后立刻登出
现象：登录成功 → 关掉 Trae 再打开 → 又需要重新登录。
排查：
# 检查本地 Token 存储是否正常
# macOS
ls ~/Library/Application\ Support/Trae/Local\ Storage/
# 这里应该有以 file__*.localstorage 命名的文件
# 如果不确定，直接清除本地认证缓存后重新登录
rm -rf ~/Library/Application\ Support/Trae/Local\ Storage/如果发生在公司电脑上，可能是 IT 管理的磁盘还原策略（每次重启还原 C 盘或用户目录）。
3.5 账号被封禁或限流
现象：能登录但所有 AI 请求返回错误，或登录后提示”账号异常”。
常见原因：
- 国际版使用国内代理触发了风控规则
- 短时间内大量 API 调用（如 SOLO 循环失控）
- 多个账号共享同一个 IP（常见于团队共享代理）
解决：
- 联系官方客服（国内版通过 trae.cn 在线客服，国际版发邮件至 support@trae.ai）
- 等待自动解封（一般 24 小时后自动解除）
04 模型访问错误
4.1 “Model not available” / “模型不可用”
现象：Chat 或 Builder 发送消息后，AI 返回 “Model not available” 或 “当前模型不可用”。
原因：
| 原因 | 特征 | 解决 |
|---|---|---|
| 套餐额度耗尽 | 之前还能用，突然不能了 | 检查订阅页面剩余额度 |
| 模型维护中 | 所有用户同时报错 | 查看 status.trae.ai 或 trae.cn 公告 |
| 区域限制 | 特定模型在你所在区域不可用 | 切换区域或换模型 |
| 模型切换了 | 免费模型被替换 | 在设置中重新选择可用模型 |
具体操作：
排查步骤：
1. 检查当前模型：Trae 设置 → 模型 → 确认选择了可用模型
2. 检查额度：国内版看右上角头像 → 我的订阅；国际版看 Settings → Subscription
3. 查看服务状态：https://status.trae.ai
4. 切换到其他模型试试（如从 Claude 切到 GPT）4.2 “Rate limit exceeded” / 请求过于频繁
现象：正常使用中突然出现限流提示，所有 AI 请求被拒绝。
SOLO 限流：这是 SOLO 模式的典型问题。SOLO 在自动执行时可能会在短时间内发出大量请求，触发模型供应商的限流策略。
解决方案：
方案一：降低频率
在 .trae/rules 中添加：
"SOLO 每次请求之间等待 3 秒"
方案二：切换模型
用一个不容易被限流的模型（如 GPT-4o 比某些高频模型更稳定）
方案三：等待
限流通常是暂时的，等待 1-5 分钟自动恢复Free 套餐的每日请求上限：
| 套餐 | Chat/Build 限制 | 补全限制 |
|---|---|---|
| 国内免费版 | 约 200 次对话/天 | 2000 次/月 |
| 国际 Free | $3 额度用完即停 | 同上 |
| 国际 Pro | $20 额度起 | 无额外限制 |
4.3 “Token quota exceeded”
现象：国际版出现 “Token quota exceeded”。
国际版在 2026 年 2 月切换为按 token 计费。出现此提示说明已超出预充值额度。
- 检查 Settings → Usage 面板的 token 消耗曲线
- 如果是因为 SOLO 跑了一个大项目耗尽了额度，充值后继续
- 可以设置月度预算上限预防意外超支
4.4 模型回答质量突然下降
现象：同一个模型之前回答很好，今天变得很差——回答很短、拒绝执行、或重复无意义内容。
排查：
- 是否无意中切换了模型：检查设置中的当前模型
- 上下文是否污染：如果 Chat 历史很长（50+ 轮），开一个新会话测试
- 规则文件是否干扰：临时移除
.trae/rules测试 - 插件是否修改了系统指令：禁用最近安装的插件
05 Builder 预览不加载
现象
Builder 创建项目后，Webview 预览窗口显示白屏、或显示”无法预览”。
5.1 预览的基本工作原理
理解 Builder 预览的机制有助于排查：
Builder 启动项目
→ 在后台运行 dev server（如 npm run dev / vite）
→ dev server 绑定到本地端口（如 localhost:5173）
→ Trae Webview 读取该端口 → 渲染在预览面板所以预览不加载本质上是本地 dev server 没有正常运行。
5.2 排查步骤
第一步：看终端输出了什么
Builder 执行完代码生成后，会自动在终端执行 npm install 和 npm run dev。切换到内置终端面板查看：
[21:30:05] Starting: npm install
[21:30:10] ✓ npm install completed
[21:30:10] Starting: npm run dev
[21:30:12] ✗ Error: Module not found: 'react-dom'看到具体错误就知道怎么修了——通常是依赖安装失败。
第二步：手动验证 dev server
在终端中手动启动项目：
cd /path/to/builder/project
npm install # 重新安装依赖
npm run dev # 手动启动如果终端输出 Local: http://localhost:5173/ 且浏览器能打开，说明项目本身没问题。问题在 Trae 的 Webview 和 dev server 的端口通信。
第三步：检查端口是否被占用
# 查看 5173 / 3000 端口被谁占用
lsof -i :5173
# 如果有其他进程占了端口，杀掉它
kill -9 <PID>第四步：重新加载 Webview
点击预览面板右上角的刷新按钮（环形箭头）。如果仍然白屏，在命令面板中运行：
Cmd+Shift+P → Developer: Reload Window5.3 常见 Builder 预览问题速查
| 现象 | 最可能的原因 | 解决 |
|---|---|---|
| 白屏但终端有输出 | Webview 缓存 | 刷新预览面板 |
| 白屏且终端无任何输出 | dev server 没启动 | 手动 npm run dev 看报错 |
| 显示”无法连接到服务器” | 端口配置不一致 | 查看 dev server 实际端口，确认预览端口匹配 |
| 页面样式错乱 | 框架版本冲突 | 检查 package.json 中的框架版本 |
| 预览显示旧内容 | 热更新失效 | 手动保存文件触发重新编译 |
06 网络与代理问题
这是 Trae 用户遇到最多的问题类型。国际版用户在国内使用必须配代理，但代理配置本身也会引入新问题。
6.1 国际版连接失败
现象：Trae 启动后右下角显示”离线”，AI 请求全部超时。
诊断命令：
# 测试 Trae 到 AI 服务的连通性
trae --doctor # 查看网络连接状态
# 测试更细致的链路
curl -I https://api.trae.ai/health
# 如果 curl 不通 → 网络问题
# 如果 curl 通但 trae 不通 → 代理配置问题核心原则：
国内版 → 不需要任何代理 → 如果连不上，检查 DNS 和防火墙
国际版 → 必须配代理 → 如果连不上，先查代理6.2 Trae 代理配置
Trae 默认使用系统代理。如果你的代理软件（如 Clash、Surge、V2Ray）设置为系统代理，Trae 会自动使用。
如需单独为 Trae 配置代理：
// Cmd+Shift+P → Preferences: Open User Settings (JSON)
{
"trae.http.proxy": "http://127.0.0.1:7890",
"trae.https.proxy": "http://127.0.0.1:7890"
}代理配置常见错误：
| 错误 | 症状 | 解决 |
|---|---|---|
| 代理端口写错 | 所有请求超时 | 确认代理软件的实际端口（多在 7890/7891/1080） |
| 用了 SOCKS5 但配成了 HTTP | 部分请求失败 | Trae 只支持 HTTP 代理，SOCKS5 需要转换 |
| 代理软件规则没包含 trae.ai | 国际版请求不走代理 | 在代理软件中添加 trae.ai 规则 |
| 开了代理但忘记启动软件 | 连接被拒绝 | 检查代理软件是否在运行 |
| 同时开了多个代理软件 | 端口冲突 | 只开一个代理软件 |
6.3 代理规则配置
如果你的代理软件是规则模式（如 Clash 的 Rule 模式），需要确保以下域名走代理：
# 必须走代理的 Trae 域名
trae.ai
api.trae.ai
auth.trae.ai
*.trae.ai
# 模型 API 域名
api.anthropic.com
api.openai.com
# 代码补全
completion.trae.ai在 Clash 中配置规则示例：
# config.yaml 规则部分
- DOMAIN-SUFFIX,trae.ai,Proxy
- DOMAIN-SUFFIX,anthropic.com,Proxy
- DOMAIN-SUFFIX,openai.com,Proxy
- DOMAIN-SUFFIX,github.com,Proxy6.4 国内版网络问题
国内版不需要代理，但以下情况仍可能出问题：
企业内网限制：某些公司防火墙会拦截非业务流量。尝试：
- 切换手机热点测试是否公司网络问题
- 联系 IT 部门将
trae.cn、*.volcengine.com加入白名单
DNS 污染：
# 测试 DNS
nslookup trae.cn
# 如果返回的 IP 明显不对（如指向国外 IP），修改 DNS
# 临时解决：修改系统 DNS 为 114.114.114.114（国内）或 8.8.8.8IPv6 问题：部分国内网络 IPv6 不稳定。在 Trae 设置中禁用 IPv6：
{
"trae.network.disableIPv6": true
}6.5 延迟高但没断开
现象：AI 能响应但很慢，每次等待 10+ 秒。
排查：
# 测量代理延迟
trae --doctor # 看网络延迟
# 如果是国际版，检查代理线路质量
# 优质线路延迟应在 200ms 以内改善方法：
- 更换代理协议：SS/V2Ray 通常比 HTTP 代理更快
- 选择离你物理位置更近的节点
- 国内版永远比国际版快——如果主要是国内场景，考虑切换到国内版
07 SOLO 卡住 / 做出错误决策
SOLO 模式是 Trae 的功能高地，也是问题高发区——因为 AI 的”自主性”越高，不可控因素越多。
7.1 SOLO 卡住不动
现象：SOLO 的进度条/状态提示长时间没有变化（5 分钟以上）。
诊断清单：
1. 看终端输出 —— SOLO 是不是在执行耗时命令（npm install、编译）？
→ 如果是，耐心等待。npm install 大项目可能需要 3-5 分钟
2. 看 Chat 面板 —— SOLO 是不是在等待你确认？
→ 切换到 Chat 面板，看有没有未处理的确认按钮
3. 看上下文长度 —— SOLO 是不是被超长上下文卡住了？
→ 如果 SOLO 已经执行了几十步，上下文窗口可能被撑满
4. 看日志文件 —— 有没有报错？
→ tail -f ~/Library/Application\ Support/Trae/logs/ai-service.log | grep ERROR解决步骤（按顺序尝试）：
步骤 1：点击 SOLO 面板的"暂停/继续"按钮
有时候 SOLO 只是 UI 状态显示异常
步骤 2：重启 SOLO
如果有"重启"按钮，点击它。SOLO 会重新执行失败的任务
步骤 3：终止当前 SOLO 会话
如果彻底卡死，终止任务。SOLO 会回滚未完成的改动
步骤 4：拆解任务后重试
"帮我做一个电商网站" → "先做商品列表页，其他后面再加"
任务越小，SOLO 越稳定7.2 SOLO 做了不该做的改动
现象：SOLO 修改了你没让它改的文件、或者把代码改坏了。
SOLO 的”自主性”边界：
你告诉 SOLO → "修复登录页的按钮样式"
SOLO 理解 → "好的，我找到了按钮代码"
SOLO 可能做 → "这个按钮组件在一个公共目录，附近的 header 组件也有样式问题，我一起修了"
结果 → 按钮样式确实好了，但 header 被你本来没想改的代码搞坏了这是 SOLO 模式下最核心的认知问题：AI 的”理解”和你说的可能不完全一致。AI 会”好心办坏事”——因为它看到了”相关”代码，就顺手改了。
标准应对流程：
# 第一步：看看 AI 到底改了哪些文件
git diff
# 第二步：保留你想改的，恢复你不想改的
git checkout -- src/components/Header.tsx # 只恢复 header 文件
# 或者使用 git restore（新版本 git）
git restore src/components/Header.tsx预防策略：
在 .trae/rules 中限定 SOLO 的修改范围：
# .trae/rules/solo-rules.md
## 修改范围限制
在进行任何修改之前，请先确认修改范围：
1. 只修改我明确提到的文件
2. 如果发现"相关"文件需要修改，先在 Chat 中询问我
3. 不要碰 node_modules、dist、build 目录
4. 不要修改环境变量文件 (.env.*)7.3 SOLO 循环执行同一任务
现象：SOLO 反复执行同一个步骤，“Fix → Test → Fail → Fix” 无限循环。
原因分析：
最常见的情况：
SOLO 改了一个 Bug
→ 自动运行测试
→ 测试还是没过（可能是单测本来就不稳，或者是相关功能被改坏了）
→ SOLO 又"修"一次
→ 测试还是没全过
→ 死循环解决方案：
方案一：停止后手动中断循环
1. 点击"停止"终止 SOLO
2. 手动检查测试失败的原因
3. 修复后重新启动 SOLO
方案二：告诉 SOLO 跳过测试（仅在确定测试有问题时）
"不要运行测试，直接完成任务"
方案三：限制重试次数
在 .trae/rules 中添加：
"如果同一个任务重试 3 次仍未解决，停止并报告我"7.4 SOLO 生成了大量无效文件
现象：SOLO 创建了大量你不需要的文件（如重复的配置文件、中间文件）。
原因：
- AI 对项目结构理解偏差
- 任务描述过于模糊，AI 自行做了过多决策
预防：
构建前给 SOLO 明确的结构约束：
✅ 好：
"在 src/pages/ 下创建一个 About.tsx 页面组件，
不需要样式文件和测试文件"
❌ 差：
"加一个关于页面"事后清理：
# 看看 SOLO 创建了哪些新文件
git status
# 对新增的可疑文件，用 git clean 清理
git clean -n # 预览要删除的文件
git clean -f # 删除未追踪的文件08 性能问题
8.1 启动慢、编辑器卡顿
现象：Trae 启动需要 30 秒以上，打字有延迟、Tab 切换卡顿。
排查步骤：
1. 检查插件数量
这是编辑器变慢的最常见原因。Trae 能兼容 VS Code 扩展，但装太多会显著拖慢启动速度。
检查方法：扩展面板 → 看已安装数量
理想值：10-15 个以内的必要扩展
预警值：30+ 个扩展禁用不常用的扩展，特别是这些容易拖慢速度的：
| 扩展类型 | 影响 | 替换方案 |
|---|---|---|
| 大型语言包（如 10+ 语言） | 启动慢 | 只保留中文和英文 |
| 主题包（如 Material Theme） | 启动慢 | 用 Trae 内置主题 |
| 多余的语言服务器 | 内存占用 | 不需要的语言禁用对应插件 |
| 实时协作插件 | CPU 持续占用 | 需要时再启用 |
2. 检查内存占用
# macOS
top -o mem | grep Trae
# 如果 RSS 超过 2 GB，说明内存泄漏
# 尝试
# 1. 关闭未使用的项目窗口
# 2. 重启 Trae（内存泄漏通常重启后解决）
# 3. 禁用大体积扩展3. 大文件问题
Trae 的 AI 功能依赖于语法分析。打开超过 10MB 的单个文件会导致编辑器明显卡顿。
- 超过 10MB 的文件：考虑分割
- 超过 1MB 的 JSON 文件：语法高亮会变慢，可以暂时在设置中禁用大文件的语法解析
8.2 AI 响应慢
现象：Chat 或 Builder 的 AI 回复比平时慢很多。
排查：
1. 检查网络延迟（trae --doctor）
2. 切换到更快模型（国内版豆包 Pro 比 Claude 快）
3. 检查上下文长度——长对话后期 AI 响应会变慢
4. 检查是否有其他程序占满 CPU（如 Docker、编译任务）
5. 国际版检查代理线路质量AI 响应速度对比：
| 模型 | 首 token 延迟 | 适用场景 |
|---|---|---|
| 豆包 Pro（国内版） | ~0.5s | 速度优先，日常对话 |
| GPT-4o | ~1s | 均衡型 |
| Claude Sonnet 4 | ~1.5s | 代码质量优先 |
| GPT-5.4 | ~2s | 复杂推理任务 |
8.3 磁盘空间暴涨
现象：Trae 占用几十 GB 磁盘空间。
常见占用来源：
# 查看 Trae 的缓存目录
du -sh ~/Library/Application\ Support/Trae/
# 最大的通常在这里
du -sh ~/Library/Application\ Support/Trae/CachedData/
du -sh ~/Library/Application\ Support/Trae/CachedExtensionVSIXs/清理缓存：
# 清理扩展缓存（可安全删除）
rm -rf ~/Library/Application\ Support/Trae/CachedExtensionVSIXs/
# 清理缓存数据
# 通过 Trae 内部：Cmd+Shift+P → Developer: Clear Cache
# 清理会话历史（不会影响代码，仅清除对话记录）
# Trae → 设置 → 清除聊天历史09 扩展冲突
9.1 扩展不兼容
现象：安装某个 VS Code 扩展后，Trae 右上角弹出”扩展不兼容”提示。
Trae 和 VS Code 的扩展生态关系：
VS Code 扩展 → 不一定能直接在 Trae 运行
原因：Trae 基于 VS Code 内核但不是 100% 兼容
表现：大部分能运行（95%+），少部分报错
排查：看官方不兼容列表官方已知不兼容的扩展类型（更新于 2026 Q2）：
| 扩展类型 | 代表 | 状态 | 替代方案 |
|---|---|---|---|
| AI 编程助手 | GitHub Copilot、Cursor Tab | 明确冲突 | ❌ 不要同时装——AI 补全会冲突 |
| 代码审查工具 | CodeRabbit | 部分兼容 | 使用 Trae 内置 Chat 审查 |
| 远程开发 | Remote - SSH、Dev Containers | 兼容但注意版本 | Trae 内置 Remote-SSH |
| 数据库工具 | SQLTools | 兼容 | 正常使用 |
9.2 AI 补全和 Copilot 冲突
现象：装了 Copilot 后，Trae 自身的 AI 代码补全”和 Copilot 的补全同时出现、互相覆盖。
核心原则：不要在 Trae 里装其他 AI 编程助手。
Trae 本身就是 AI IDE，内置补全引擎。
再装 Copilot、Codeium、Tabnine 等：
- 补全互相打架
- 编辑器响应变慢
- 两个 AI 模型同时消耗 Token
- 甚至可能互相覆盖可接受的内容9.3 扩展导致崩溃
现象：安装扩展后 Trae 闪退或启动即崩溃。
# 1. 安全模式启动（禁用所有扩展）
trae --safe
# 2. 在安全模式下逐一排查
# 扩展面板 → 已安装 → 逐个启用 → 看哪个导致崩溃
# 3. 如果找到罪魁祸首
# 扩展面板 → 点击扩展 → 卸载
# 4. 如果进去不了扩展面板
# 直接删除扩展目录
rm -rf ~/.trae/extensions/<冲突扩展名>10 Git 集成问题
10.1 Trae 识别不到 Git
现象：打开项目文件夹后，Git 功能灰显，提示”未找到 Git”。
排查：
# 1. 确认 Git 已安装
git --version
# 2. 确认 Trae 能找到 Git
# 如果 Git 安装在非标准路径，需要在设置中指定：
# Settings → Git: Path → 输入 Git 可执行文件路径
# 3. macOS 用户特别注意
# 如果你是通过 Xcode Command Line Tools 安装的 Git
xcode-select --install # 如果首次，先装
xcode-select -p # 确认路径
# 通常路径是 /Library/Developer/CommandLineTools/usr/bin/git10.2 Git 权限问题
现象：Trae 里能查看状态和 diff，但 commit 失败。
排查：
# 1. 检查 Git 全局配置
git config --global user.name
git config --global user.email
# 如果为空，需要配置：
git config --global user.name "你的名字"
git config --global user.email "你的邮箱"
# 2. 检查 SSH key 是否有效（用于 remote 操作）
ssh -T git@github.com
# 如果报错，重新生成 SSH key 并添加到 GitHub/GitLab10.3 大仓库 / Monorepo 问题
现象：在大型 monorepo 中，Trae 的 Git 操作（如 status、diff）非常缓慢。
原因：Trae 会对项目做全量文件分析。在包含数千个文件的 monorepo 中，
// 在设置中限制 Git 扫描深度
{
"git.maxScannedFolders": 1000
}
// 或者定期清理 .git 对象（保守操作）
git gc --prune=now最佳实践：在 monorepo 中只打开你正在工作的子目录，而不是整个仓库根目录。
10.4 SOLO 模式下的 Git 异常
现象：SOLO 生成了 commit 但 message 毫无意义，或 commit 没有内容。
解决方案：
◈ 问题：commit message 太笼统
→ 在 .trae/rules 中指定 commit 规范
"commit message 必须遵循 conventional commits 规范，
格式为 <type>: <description>"
◈ 问题：commit 没有内容（空 commit）
→ 检查 SOLO 是否修改了被 .gitignore 排除的文件
→ 检查 SOLO 是否写出了空文件10.5 合并冲突解决失败
现象：Builder 或 SOLO 模式解决了合并冲突，但结果代码有问题。
原则：
AI 可以帮你识别冲突区域，但合并冲突的解决方案必须逐段审查。AI 看到的是语法层面的冲突，看不到业务层面的意图。
在实际工作中，合并冲突的解决应该：
1. 使用 SOLO/Builder 生成初始合并结果（AI 处理语法冲突）
2. 手动逐段审查 AI 的合并结果（你验证业务逻辑）
3. 运行测试确保合并后功能正常
4. 只有在全部通过后，才接受合并11 其他常见问题
11.1 内置终端无法使用
现象：按 Cmd+J 或 Ctrl+ ` 打开的终端面板显示空白或报错。
排查：
# Windows 用户最常见：默认 Shell 路径不对
# 设置 → Terminal › Integrated › Shell: Windows → 确认路径正确
# 默认：C:\Windows\System32\cmd.exe
# macOS 用户：如果用的不是 zsh
# 设置 → Terminal › Integrated › Shell: Osx
# 输入 /bin/zsh 或 which zsh 的输出11.2 配置同步失败
现象：Settings Sync 打开后报错。
国内版使用火山引擎账号同步，国际版使用 GitHub 账号同步。检查对应账号的登录状态。
11.3 安全弹窗 “This application wants to…”
现象：每次启动都弹出各种权限请求。
macOS 权限设置：
系统设置 → 隐私与安全性：
├── 辅助功能 → 允许 Trae（终端控制需要）
├── 自动化 → 允许 Trae（脚本执行需要）
├── 文件和文件夹 → 允许 Trae 访问项目目录
├── 屏幕录制 → 允许 Trae（如需截图/屏幕识别功能）11.4 MCP 连接失败
详见 13-MCP 集成 的排查章节。基本流程是：
# 1. 检查 MCP 服务是否启动
ps aux | grep mcp
# 2. 检查 MCP 配置
cat .trae/mcp.json
# 3. 测试 MCP 连接
trae --doctor mcp12 排查工具体系总览
当遇到任何问题时，最佳路径是：
遇到问题
│
▼
┌───────────────────────┐
│ 1. 运行 trae --doctor│
│ 2. 查看终端输出/日志 │
└───────┬───────────────┘
│
▼
医生能查出问题吗？
┌─────┴─────┐
│是 │否
▼ ▼
跳到对应章节 ┌──────────────────┐
解决问题 │逐个隔离变量 │
│1. 安全模式启动 │
│2. 禁用所有扩展 │
│3. 重启 Trae │
│4. 检查系统更新 │
│5. 卸载重装 │
└──────────────────┘能用 --doctor 解决的，不要手动排查。能看日志解决的，不要妄加猜测。
13 如何高效寻求帮助
如果自己排查仍无法解决，按以下格式提供信息，可以大幅提高他人帮你的效率：
【Trae 版本】trae --version 的输出
【系统版本】macOS 14.5 / Windows 11 / Ubuntu 24.04
【版本类型】国内版 / 国际版
【问题描述】一句话说清楚现象
【重现步骤】1. 打开项目 → 2. 切换到 Builder → 3. 输入 xxx → 4. 看到白屏
【诊断结果】trae --doctor 的输出
【相关日志】ai-service.log 中最近的 ERROR 行
【尝试过的】1. 重启 Trae → 2. 重装扩展 → 3. 切模型求助渠道：
| 版本 | 渠道 | 入口 |
|---|---|---|
| 国内版 | 在线客服 | trae.cn 官网 → 右下角客服图标 |
| 国内版 | 飞书/抖音群 | trae.cn 底部扫码加入 |
| 国际版 | 官方论坛 | forum.trae.ai |
| 国际版 | GitHub Issues | github.com/trae-ai/trae/issues |
| 国际版 | support@trae.ai |
14 小结
| 章节 | 核心排查思路 |
|---|---|
| 安装失败 | 检查系统版本、磁盘空间、Gatekeeper/杀毒软件拦截 |
| 登录问题 | 先确认版本——国内版用手机号，国际版用邮箱/GitHub |
| 模型错误 | 检查套餐额度、模型状态、限流状态 |
| Builder 预览白屏 | 去终端看 dev server 输出，手动跑一遍项目 |
| SOLO 卡住 | 看终端、看待确认、看上下文长度、拆解任务 |
| 网络代理 | 国内版不要代理，国际版必须代理——配好规则 |
| 性能问题 | 扩展越少越快，缓存在定期清 |
| 扩展冲突 | 不要同时装多个 AI 编程助手 |
| Git 问题 | 检查 git 安装路径、全局配置、SSH key |
| 万能手段 | 安全模式、重启、--doctor、日志 |
一句话总结：80% 的问题出现在版本选错和网络不通这两件事上。先用 trae --doctor 扫一遍，90% 的问题定位在 30 秒内完成。
下一篇：33 术语表 —— Trae 全系列核心术语速查。