UI-TARS-desktop开发环境搭建指南：从准备到进阶

准备阶段：环境配置与系统适配

本阶段需完成3项核心任务：验证系统兼容性、配置开发工具链、获取项目源码，为后续开发奠定基础。

1.1 系统兼容性验证

UI-TARS-desktop基于Electron和TypeScript构建，对运行环境有特定要求。Node.js版本兼容性是关键前提，项目需要v20.x.x版本以确保依赖安装和构建过程顺利。

# 检查Node.js版本
node -v

预期结果：输出v20.x.x版本号。若版本不符，需使用nvm或官方安装包切换至Node.js v20系列。

背景原理：Electron框架对Node.js版本有严格依赖，不同版本的Electron需要特定范围的Node.js支持，使用不兼容版本会导致构建失败或运行时错误。

1.2 开发工具链配置

根据操作系统安装必要的系统依赖，确保编译过程顺利进行。

# Ubuntu/Debian系统
sudo apt-get install build-essential libx11-dev libxkbfile-dev

# macOS系统
xcode-select --install

预期结果：系统依赖安装完成，无错误提示。

项目提供环境诊断工具，可在克隆仓库后执行：

# 克隆仓库后执行环境诊断
pnpm run diagnose

预期结果：显示环境检查报告，所有检查项均通过。

1.3 源码获取与目录结构解析

使用Git克隆项目源码，并了解核心目录结构。

# 克隆项目仓库
git clone https://gitcode.com/GitHub_Trending/ui/UI-TARS-desktop
cd UI-TARS-desktop

# 创建开发分支
git checkout -b feature/your-feature-name

预期结果：项目成功克隆到本地，当前分支为新创建的开发分支。

核心目录说明：

• apps/ui-tars: 主应用代码，包含Electron主进程和渲染进程
• packages/: 项目内部依赖包
• docs/: 项目文档和使用指南
• examples/: 应用示例和配置样例

实施阶段：环境搭建与应用运行

本阶段需完成2项核心任务：配置依赖管理工具、部署开发/生产环境，实现应用的本地运行与构建。

2.1 依赖管理工具配置

项目推荐使用pnpm v9.10.0及以上版本进行依赖管理，以确保依赖安装的一致性和速度。

# 全局安装pnpm
npm install -g pnpm

# 验证pnpm版本
pnpm -v

预期结果：输出9.10.0及以上版本号。

配置国内镜像源加速依赖下载：

# 配置npm镜像源
pnpm config set registry https://registry.npmmirror.com

# 配置Electron镜像源
pnpm config set electron_mirror https://npmmirror.com/mirrors/electron/

预期结果：镜像源配置成功，无错误提示。

2.2 开发环境部署

安装项目依赖并启动开发调试模式，支持代码热重载。

# 安装项目依赖
pnpm install

# 预构建核心依赖
pnpm run build:deps

# 启动开发模式
cd apps/ui-tars
pnpm run dev

预期结果：Electron应用窗口自动打开，显示UI-TARS-desktop欢迎界面。

图1：UI-TARS-desktop应用启动后主界面，显示"Computer Operator"和"Browser Operator"两个主要功能入口

2.3 生产环境构建

构建可执行应用程序，生成适用于不同操作系统的安装包。

# 返回项目根目录
cd ../..

# 执行生产构建
pnpm run build

预期结果：构建完成后，在out/目录下生成对应操作系统的安装包。

不同操作系统安装指南：

🔧 Windows系统：

1. 找到out/目录下的.exe安装文件
2. 双击运行，出现安全提示时点击"仍要运行"

图2：Windows系统安装时可能出现的SmartScreen安全提示，需点击"仍要运行"继续安装

🔧 macOS系统：

1. 找到out/目录下的.dmg文件
2. 双击打开，将应用图标拖入Applications目录

图3：macOS系统安装界面，显示将UI TARS应用拖入Applications文件夹

进阶阶段：权限配置与问题排查

本阶段需完成2项核心任务：配置系统权限、掌握常见问题排查方法，确保应用功能完整和稳定运行。

3.1 系统权限配置

UI-TARS-desktop需要特定系统权限才能正常工作，特别是在macOS系统上。

macOS权限配置步骤：

1. 打开"系统设置" → "隐私与安全性"
2. 在"辅助功能"中启用UI-TARS
3. 在"屏幕录制"中启用UI-TARS

图4：macOS系统隐私与安全性设置界面，显示UI-TARS需要的辅助功能和屏幕录制权限

权限配置参数说明：

权限项	作用	必要性
辅助功能	允许应用控制鼠标、键盘操作	必需
屏幕录制	允许应用捕获屏幕内容进行视觉分析	必需
文件访问	允许应用读取本地文件系统	可选，根据使用场景

3.2 常见问题排查

采用"症状-原因-解决方案"三段式排查法解决常见问题：

问题1：依赖安装失败

• 症状：pnpm install命令执行失败，出现大量依赖下载错误
• 原因：Node.js版本不兼容或镜像源配置错误
• 解决方案：

  # 安装并切换到Node.js v20
  nvm install 20 && nvm use 20
  
  # 重新配置镜像源
  pnpm config set registry https://registry.npmmirror.com
  

问题2：应用启动白屏

• 症状：开发模式下应用窗口打开后显示白屏
• 原因：Electron配置错误或前端资源构建失败
• 解决方案：

  # 检查并重新构建前端资源
  cd apps/ui-tars
  pnpm run build:web
  
  # 验证Electron配置
  cat electron.vite.config.ts
  

问题3：权限不足导致功能异常

• 症状：应用无法执行鼠标点击或屏幕捕获
• 原因：系统权限未正确配置
• 解决方案：
  1. 打开系统设置 → 隐私与安全性
  2. 找到UI-TARS应用，启用所需权限
  3. 重启应用使权限生效

3.3 开发效率提升

推荐开发工具和插件：

• 代码质量：ESLint + Prettier，确保代码风格一致
• 类型检查：TypeScript官方插件，提供类型提示
• 调试工具：Electron Developer Tools，调试主进程和渲染进程
• 构建优化：使用pnpm run dev:fast命令启动快速开发模式

环境验证清单

• [ ] Node.js版本为v20.x.x
• [ ] pnpm版本为9.10.0及以上
• [ ] 系统依赖已安装
• [ ] 项目依赖安装成功
• [ ] 开发模式可正常启动应用
• [ ] 生产构建可生成安装包
• [ ] macOS权限已正确配置（如适用）
• [ ] 应用可正常显示主界面
• [ ] 可成功选择"Computer Operator"或"Browser Operator"功能