22 · 设置与配置 — Trae 设置的深度解析

适合读者：所有 Trae 用户
学习目标：掌握 Trae 全域设置体系，理解配置优先级，学会按项目切换配置方案

引言

Trae 是一款高度可定制的 AI IDE。它的设置体系并非单一面板，而是一套从 UI 面板到 JSON 配置文件的三层级架构。许多用户刚上手时只在「设置中心」里点几下，却不知道真正的配置能力藏在 .trae/ 文件夹、sandbox.json 和 Hook 系统中。

本文将从全局视角拆解 Trae 的整套配置体系，帮助你从「只会拖拽开关」进阶到「能手写配置管理项目」。

01 · 用户设置 vs 项目设置：三层级覆盖模型

Trae 的配置遵循 「就近覆盖」 的层级模型。理解这个模型是正确配置的前提。

核心层级

心智模型：你可以把这三层想象成「操作系统 → 软件 → 用户配置文件」的关系。全局设置定基调，项目设置定规矩，本地覆盖则是你的个人小抄。

实际场景

场景一：你在所有项目中都用 16px 字号、暗色主题——放在全局设置。
场景二：你的前端项目需要 tabSize: 2，后端项目需要 tabSize: 4——放在各自的项目设置。
场景三：你的队友用 JDK 17，你本地只有 JDK 11——用 settings.local.json 覆盖，不影响团队。

配置优先级规则

settings.local.json > settings.json（同层级）
项目 settings.json > 全局 settings.json
project_rules.md > user_rules.md

02 · Config.toml 的等价物：.trae/settings.json

如果你用过 Cursor 或 Claude Code，可能会好奇 Trae 有没有 config.toml。答案是：Trae 不使用 TOML 格式，它的配置核心是 JSON 文件。

配置文件的等价对照

.trae/ 文件夹完整结构

your-repo/
├── CLAUDE.md                   # 兼容 Claude Code 的团队规则
├── CLAUDE.local.md             # 本地规则，不提交
└── .trae/
    ├── settings.json           # 项目配置（团队共享）
    ├── settings.local.json     # 本地覆盖（已 gitignore）
    ├── mcp.json                # MCP 服务器配置
    ├── hooks.json              # Hook 自动化脚本配置
    ├── sandbox.json            # 沙箱文件/网络权限（仅项目级）
    ├── rules/
    │   ├── user_rules.md       # 个人规则（项目级生效）
    │   └── project_rules.md    # 项目规则（优先级最高）
    ├── skills/
    │   └── <skill-name>/
    │       └── SKILL.md
    └── agents/
        └── <agent-name>.md

核心 settings.json 示例

{
  "editor.fontSize": 14,
  "editor.tabSize": 2,
  "editor.formatOnSave": true,
  "trae.ai.model": "claude-sonnet-4-20250514",
  "trae.ai.codeIndex.enabled": true,
  "trae.ai.chatLanguage": "auto",
  "files.watcherExclude": {
    "**/node_modules/**": true,
    "**/dist/**": true
  }
}

实践建议：把 .trae/settings.json 提交到 Git，让整个团队共享统一的 AI 模型、代码规范和索引策略。settings.local.json 则用来放你个人的 JDK 路径或 API Key。

03 · 模型默认配置：AI 大脑的切换面板

Trae 支持多模型混合使用，它的模型配置分两个层面：GUI 预设模型和自定义模型。

预设模型

在 AI 聊天对话框右上角的设置中，你可以选择以下内置模型：

自定义模型（Settings → 模型）

Trae 支持接入任何兼容 OpenAI Chat Completions 格式的 API：

{
  "apiKey": "sk-xxx",
  "baseUrl": "https://api.example.com/v1",
  "model": "deepseek-r3"
}

应用场景：如果你的团队使用的是私有化部署的大模型，或者想用硅基流动、腾讯云 TokenHub 等第三方服务，就通过自定义模型入口配置。

模型选择的策略建议

04 · 沙箱与权限设置：安全的最后一道防线

这是 Trae 区别于普通编辑器的核心安全特性。沙箱机制确保 AI 生成的命令不会对你的系统造成意外破坏。

沙箱的工作原理

当 AI 生成一个终端命令时，Trae 的沙箱会拦截它，在受限环境中执行。这个环境对文件系统的访问有严格限制：

自定义沙箱配置（sandbox.json）

如果你想扩展沙箱的读写权限，可以在 ~/.trae-cn/sandbox.json（全局）或 .trae/sandbox.json（项目级）中配置：

{
  "filesystem": {
    "readWrite": ["~/my-tools", "$WORKSPACE_FOLDER/output"],
    "readOnly": ["/etc/config"]
  },
  "network": {
    "default": "allow",
    "allow": ["*.github.com:443"],
    "deny": ["*.internal.company.com"]
  }
}

注意：网络访问控制目前仅 Windows 平台支持。使用 $WORKSPACE_FOLDER 变量可以引用当前工作区路径。

命令运行模式

在「设置 → 对话流 → 自动运行命令」中，你可以选择：

⚠️ 重要提示：自动运行的命令始终在沙箱外执行。也就是说，开启「始终自动」等于完全关闭了沙箱保护。建议仅在信任的项目中开启白名单模式。

实用建议：解决沙箱写入问题

社区中常见的问题是沙箱阻止了 ~/.nvm、~/.pyenv 等目录的写入。解决方法有三种：

1. 将相关命令加入白名单（推荐）
2. 在 sandbox.json 中将目标路径加入 readWrite
3. 临时改为自动运行（事后记得改回）

05 · 主题与 UI 自定义：让编辑器长成你喜欢的样子

预设主题

Trae 内置了三种基本主题：

• 暗色（Dark）— 默认，护眼
• 深蓝（Deep Blue）— 沉稳风格
• 亮色（Light）— 白天使用

更多主题

通过「主题 → 更多主题 → 浏览其他颜色主题」，你可以访问 Trae 官方插件市场中的所有主题插件，一键安装应用。

快捷键切换主题

• macOS：Cmd + K 再按 T
• Windows：Ctrl + K 再按 T

从 VS Code / Cursor 导入主题

在「设置 → 通用 → 导入配置」中，你可以一键导入 VS Code 或 Cursor 的所有设置，包括主题、插件、代码片段和快捷键。

⚠️ 注意：导入操作会覆盖当前配置，且不可撤销。建议导入前先导出一份当前配置备份。

其他 UI 自定义选项

06 · 快捷键设置：切换你的肌肉记忆

Trae 理解开发者来自不同编辑器背景的问题，提供了灵活的快捷键方案。

内置方案

在「设置 → 通用 → 偏好设置 → 快捷键设置」中，你可以直接选择：

• VS Code 风格 — 默认，VS Code 用户无需适应
• JetBrains 风格 — IntelliJ IDEA / PyCharm 用户的福音

自定义快捷键

方式一：打开「设置 → 快捷键」，右键点击任意条目即可修改、添加或删除键绑定。
方式二：通过命令面板（Cmd/Ctrl + Shift + P）搜索「Preferences: Open Keyboard Shortcuts」。

常用快捷键速查表

恢复默认快捷键

如果你改乱了快捷键，可以通过命令面板打开 keybindings.json，清空所有自定义内容即可恢复默认。

07 · 扩展管理：站在 VS Code 生态的肩膀上

Trae 最强大的地方之一：它兼容 VS Code 插件生态。

安装扩展的三种方式

导入现有 IDE 配置

「设置 → 通用 → 导入配置」是 Migrate 利器。它支持：

• 从 VS Code 导入：插件、设置、代码片段、快捷键
• 从 Cursor 导入：同上

扩展开发

如果你有自定义需求，Trae 提供完整的 Extension API：

• Editor API — 编辑器控制、文档管理
• Workspace API — 项目、文件管理
• UI API — 自定义面板和对话框
• Themes API — 自定义主题
• AI Chat API — AI 聊天系统集成

npm install -g @trae/cli
trae package
trae publish

08 · Profile 切换：不同项目用不同配置

大型项目中，你可能会同时维护前端、后端、数据工程等多个项目，每个项目对 AI 模型、代码规范、工具链的需求都不一样。Trae 通过 配置文件分层 而不是独立 Profile UI 来解决这个问题。

目前可用的 Profile 管理方式

多项目场景实战

假设你同时维护三个项目：

~/projects/
├── frontend-react/         # React + TypeScript + Tailwind
│   └── .trae/settings.json
│       -> model: claude-sonnet-4, tabSize: 2
│
├── backend-java/           # Spring Boot + Maven
│   └── .trae/settings.json
│       -> model: claude-sonnet-4, tabSize: 4
│       -> java.configuration.runtimes: [JDK 17]
│
└── data-pipeline/          # Python + Airflow
    └── .trae/settings.json
        -> model: gpt-4o, tabSize: 4
        -> python.terminal.activateEnvironment: true

你在切换到不同项目时，Trae 会自动加载对应的 .trae/settings.json，实现隐式 Profile 切换。

全局 settings 文件路径

如果你需要在不同机器间同步全局设置，可以关注：

• macOS / Linux：~/.trae/settings.json
• Windows：%USERPROFILE%\.trae\settings.json
• Hook 配置（全局）：~/.trae-cn/hooks.json
• 沙箱配置（全局）：~/.trae-cn/sandbox.json

团队 Profile 最佳实践

1. 团队 Leader 维护 .trae/settings.json，提交到仓库
2. 团队成员 各自维护 .trae/settings.local.json，不提交
3. AI 规则 写在 .trae/rules/project_rules.md，团队共享
4. 个人习惯 写在 .trae/rules/user_rules.md，可提交也可 gitignore

09 · 对话流与智能体设置：微调 AI 行为

除了文件配置，Trae 的设置中心还提供一系列影响 AI 行为的开关。

关键设置项

自定义提示音

Trae 支持上传自定义 MP3 文件作为：

• 任务完成提示音
• 等待操作提示音
• 异常中断提示音

10 · 综合配置工作流：一个完整的项目初始化清单

让我们把以上所有知识串起来，模拟一个新项目从零开始的配置全流程：

【第 1 步】全局设置（一次配置，终身使用）
  ├── 选择暗色主题
  ├── 设置语言为简体中文
  ├── 如果从 VS Code 迁移，导入配置
  └── 选择 VS Code 风格快捷键

【第 2 步】项目级 .trae/ 目录初始化
  ├── mkdir .trae
  ├── settings.json：
  │   - editor.tabSize: 4
  │   - trae.ai.model: claude-sonnet-4
  │   - trae.ai.codeIndex.enabled: true
  └── 提交到 Git

【第 3 步】安全配置
  ├── 设置命令运行模式为「白名单」
  ├── 在 sandbox.json 中添加项目输出目录为 readWrite
  └── 如果担心网络泄漏，配置 network.deny

【第 4 步】AI 规则
  ├── project_rules.md：项目技术栈、命名规范、测试要求
  └── user_rules.md：个人偏好

【第 5 步】本地覆盖（不提交）
  └── settings.local.json：本机 JDK/Python 路径

总结

🎯 核心心法：把共性的放全局，把个性的放项目，把私密的放本地覆盖。提交到 Git 的配置应当对团队所有成员都有意义。

下一篇

23 · 智能体与自定义 Skills — 深入 Trae 的 Agent 管理和 Skill 编写，学习如何为 AI 定义专属行为规则和自动化技能。

本文基于 Trae CN 文档及社区最佳实践整理，配置项可能随版本更新变化，请以官方文档为准。