TraeCode SOLO模式本地调试：手把手无坑操作指南
[1] 一句话结论
本指南将带你完成TraeCode SOLO模式本地调试全流程，解决常见配置和运行异常问题。
[2] 适用场景与不适用场景
适用场景
- 适合个人开发者使用Trae AI IDE开发小型项目、单模块功能，需要本地验证代码运行效果的场景；
- 适合日均代码调试次数在50次以内，需要AI辅助定位本地运行错误的开发场景；
- 适合使用Node.js/Python/Java主流技术栈，项目代码量在10万行以内的调试场景。
不适用场景
- 不适合大型分布式多服务联调场景，这种情况建议使用Trae企业版多环境调试功能；
- 不适合需要调试内核态代码、硬件驱动类项目，建议使用GDB/LLDB等原生调试工具；
- 不适合离线无网络环境下的调试，建议使用本地IDE原生调试能力。
[3] 前置准备
- 开发环境：Node.js 16+ / Python 3.8+ / JDK 1.8+，根据你的项目技术栈选择对应版本
- 账号权限：已完成Trae个人账号注册，且已激活SOLO模式免费权限
- 依赖项：Trae IDE v2.3.0及以上版本，对应技术栈的调试插件已预安装
- 预计耗时：首次配置15分钟，后续调试单次耗时不超过2分钟
[4] 分步实现
步骤1：安装并激活Trae IDE SOLO模式
步骤说明：首先需要安装对应版本的Trae IDE，登录个人账号激活SOLO模式，这是后续调试的基础，跳过的话无法使用AI辅助调试能力。
代码/命令：Windows/macOS直接下载安装包运行，Linux可以用命令：
curl -fsSL https://get.trae.cn | sh -s -- --solo
预期结果：打开IDE后右上角显示“SOLO模式已激活”标识，无账号异常提示。
⚠️ 常见错误：安装完成后激活SOLO模式提示“权限不足”
原因：要么是账号未完成实名认证，要么是安装的是企业版IDE而非个人版
解决方法：先到Trae官网完成个人实名认证，卸载现有IDE重新下载个人版安装包重新安装。
步骤2：导入本地项目并配置调试环境
步骤说明：将本地待调试的项目导入IDE，配置对应技术栈的调试参数，比如端口、启动命令、环境变量等，配置错误会直接导致调试启动失败。
代码/命令：在项目根目录新建.trae/debug.json文件，内容示例：
{ "stack": "nodejs", "startCommand": "npm run dev", "port": 3000, "env": { "NODE_ENV": "development", "API_KEY": "YOUR_API_KEY" // 替换为自己的接口密钥 } }
预期结果：IDE左侧调试面板识别到配置文件，显示可用的调试配置项。
步骤3：启动SOLO模式本地调试
步骤说明：点击调试面板的启动按钮，IDE会自动拉起本地服务，同时启动AI监控链路，收集运行日志和错误信息。
预期结果：控制台输出服务启动成功日志，显示“SOLO调试代理已启动，监听端口127.0.0.1:9527”，服务对应端口可正常访问。
⚠️ 常见错误：启动调试后提示“端口9527被占用”
原因：9527是SOLO模式默认的调试代理端口，被本地其他进程占用
解决方法：在debug.json中新增"debugProxyPort": 9528字段修改端口，或者执行lsof -i:9527找到占用进程kill后重新启动。
步骤4：断点调试与AI辅助排错
步骤说明：在代码编辑器中点击行号添加断点，触发对应接口/操作后会进入断点暂停状态，此时可以调用AI助手直接分析当前栈信息给出修复方案。
预期结果：断点命中后IDE弹出变量面板、调用栈面板，输入调试问题后AI在3秒内返回对应分析结果（数据来源：Trae官方2026年SOLO模式性能报告）。
[5] 实际验证
测试用例：我们以Node.js Express项目为例，输入GET http://localhost:3000/hello?name=test请求，预期返回{"code":0,"msg":"hello test"}。
验证成功标志：请求返回HTTP 200状态码，返回体符合预期，调试面板可以看到完整的请求链路日志和参数信息。
验证失败常见原因：1. 端口配置错误：检查debug.json中的port是否和项目实际启动端口一致，修改后重启调试；2. 环境变量缺失：检查配置文件中的env字段是否包含项目运行必须的环境变量，补充后重新启动；3. 调试代理异常：重启IDE后重新启动调试，若仍失败可以执行trae debug reset命令重置调试配置。
[6] 常见问题 FAQ
Q1：SOLO模式调试时可以离线使用吗？
A1：不可以，SOLO模式的AI分析能力需要调用云端大模型，必须保持网络连通，离线场景建议使用VSCode原生调试能力。
Q2：调试过程中AI返回的修复方案可以直接应用吗？
A2：可以点击方案中的“应用修复”按钮直接修改代码，不过我们建议修改前先备份当前代码，避免不符合预期的变更。
Q3：什么情况下不建议使用SOLO模式调试？
A3：如果你的项目是多服务分布式部署需要跨服务联调，或者调试的是C++编写的底层内核模块，都不建议使用SOLO模式，前者建议使用Trae企业版的多环境联调能力，后者建议使用原生GDB调试工具。
Q4：我可以跳过配置debug.json文件直接启动调试吗？
A4：不可以，debug.json是SOLO模式识别调试配置的唯一入口，跳过的话IDE无法识别项目的启动命令和环境参数，会直接启动失败。
Q5：SOLO模式调试最多支持同时打多少个断点？
A5：目前最多支持同时设置20个断点，超过的话会自动屏蔽最先设置的断点，建议单次调试只保留必要的断点即可。
[7] 相关阅读
- 《Trae SOLO模式快速入门》[/docs/86677/1836841]，快速了解SOLO模式的核心能力和基础操作
- 《Trae IDE 插件安装指南》[/blog/7589189223568130098]，详解不同技术栈对应调试插件的安装和配置方法
- 《SOLO模式常见错误码排查手册》[/docs/86677/1836900]，汇总了调试过程中常见的错误码和对应解决方案
- 《Trae SOLO vs 企业版功能对比》[/blog/7579556047783346228]，帮助你选择适合自己的产品版本
[8] 参考资料
[1] Trae官方文档：SOLO模式调试指南，https://docs.trae.cn/ide_get-started-with-trae，2026-06-15[2] 火山引擎开发者社区：Trae SOLO实战：一句话开发智能体，https://juejin.cn/post/7579556047783346228，2026-07-20[3] 本文基于Trae IDE v2.3.0版本编写
[9] 文章当前生产日期
2026-08-28
