一、工具简介

Trae 是字节跳动推出的AI 原生集成开发环境 (AI IDE)，对标 Cursor，内置 AI 编程助手，支持自然语言生成代码、智能补全、Agent 一键生成完整项目，v3.3.51 及以上版本支持接入第三方 / 本地自定义大模型（DeepSeek、Qwen、GPT、Claude 等）抖音百科。

⚠️ 区分两个版本，不可混用

| 版本 | 官网 | 登录方式 | 特点 |

|---|---|---|---| |

国内中文版 |www.trae.cn/download| 手机号 / 抖音账号扫码登录 | 国内网络直接登录，推荐国内开发者|

| 国际英文版 |www.trae.ai/download| 海外账号 | 国内环境大概率登录失败 |

注意：Trae‑IDE（独立客户端）≠ IDEA 的 Trae 插件，二者安装流程完全不一样。

二、系统环境要求

• Windows：Win10 / Win11（x64），安装包Trae CN‑Setup‑x64.exe
• Mac：macOS 10.15+，.dmg安装包（Intel / Apple Silicon）
• 网络：国内版可直连，无需特殊网络；安装路径禁止中文、空格字符

三、详细安装步骤

Windows

1. 下载地址：【Trae中文版下载地址】，下载的安装文件名为：【Trae CN-Setup-x64.exe】
2. 右键以管理员身份运行 Trae CN‑Setup‑x64.exe
3. 勾选同意协议，下一步；可自定义安装目录​​​​​​​
4. 等待安装完成，勾选【创建桌面快捷方式】【运行 Trae】→完成

Mac

1. 下载.dmg镜像包
2. 双击打开，拖拽 Trae 图标至「应用程序」文件夹
3. 首次启动若弹出安全拦截：系统设置‑安全性与隐私‑允许运行

四、首次启动初始化配置

1. 打开软件，点击【开始使用】
2. 基础设置：选择语言（简体中文）、主题（亮色 / 暗色）
3. 【可选迁移】一键导入 VS‑Code / Cursor 的扩展、快捷键、配置
4. 【推荐】安装命令行工具，终端可直接使用命令

   trae          # 启动IDE
   trae ./demo   # 直接打开指定项目文件夹
   

5. 账号登录：国内版手机号验证码 / 抖音扫码登录，登录成功解锁全部 AI 功能

五、两大核心开发模式使用

1. Chat（对话模式）

右侧聊天框输入自然语言指令，例如：Java实现冒泡排序；支持选中代码片段，让 AI 解释、重构、修复报错。

2. Builder（智能 Agent 模式）

一句话生成完整项目脚手架，AI 自动创建多文件、目录结构、依赖配置，实现0‑1 生成项目，适合快速搭建 Demo。

额外能力：多模态输入，上传 UI 图片，AI 还原前端页面代码。

六、高级：v3.3.51+ 自定义第三方模型接入（重点避坑）

版本门槛：必须升级到 v3.3.51 及更高版本，旧版无自定义模型入口

配置入口

Trae → 设置(Settings) → Models(模型) → Custom Model(添加自定义模型)

关键知识点：Trae 存在完整 URL 开关

1. ✅【开启完整 URL】：baseURL填写完整请求终点地址（Endpoint）（CSDN 博主主流踩坑场景）
2. ✅【关闭完整 URL】：baseURL仅填写到/v1基础域名

OpenAI 兼容模型 (DeepSeek/Qwen/GPT) 配置示例

开启完整 URL（完整端点）

• Model Name：deepseek‑v3
• API‑Key：你的密钥
• baseURL：https://xxx中转域名/v1/chat/completions

关闭完整 URL（基础域名）

• baseURL：https://xxx中转域名/v1

❌ 错误写法：https://xxx.com / https://xxx.com/v1（开启完整 URL 时，只写域名会报错）

Anthropic Claude 系列配置示例

开启完整 URL：

• baseURL：https://xxx域名/v1/messages

本地大模型接入

Ollama 等 OpenAI‑兼容网关，使用上面 OpenAI 格式填写网关地址即可接入本地模型。

七、远程开发（SSH 连接 Linux 服务器）

1. Linux 服务端提前开启 SSH 服务

yum install -y openssh-server
systemctl start sshd
systemctl enable sshd
#配置免密密钥登录
ssh-keygen -t rsa -b 4096
cat ~/.ssh/id_rsa.pub >> ~/.ssh/authorized_keys
chmod 600 ~/.ssh/authorized_keys

1. Trae 左侧打开【远程资源管理器】→添加 SSH 主机，填入ssh 用户名@服务器IP连接远程开发环境

八、常见异常问题 & 解决方案

1. 无法登录
   • 原因：下载了国际英文版，国内网络环境登录受限
   • 解决：卸载，重新下载国内中文版 trae.cn/download
2. 自定义模型调用失败，接口报错
   • 核对「完整 URL」开关状态与 baseURL 填写格式是否匹配
   • 检查 API‑Key 有效性、模型 ID 名称拼写、中转服务可用性
3. Windows 启动闪退
   • 使用管理员权限启动程序；检查安装路径不含中文
4. 看不到自定义模型
   • 聊天窗口关闭 AUTO 自动模型选项，即可手动切换新增模型