UI-TARS-desktop零障碍开发环境搭建指南：从依赖配置到智能部署全流程

准备篇：开发环境基础配置

环境检查清单 🛠️

在开始前，请确保你的开发环境满足以下要求：

[!TIP] 版本不匹配会导致依赖安装失败或运行异常，建议使用nvm管理Node.js版本

node -v  # 需显示v20.x.x
pnpm -v  # 需显示9.10.0+
git --version  # 任意版本均可

术语卡片

Electron框架：基于Node.js和Chromium的跨平台桌面应用开发框架，允许使用Web技术构建原生应用

源码获取与结构解析

克隆项目代码库到本地：

git clone https://gitcode.com/GitHub_Trending/ui/UI-TARS-desktop
cd UI-TARS-desktop

项目核心目录说明：

• apps/ui-tars/：主应用目录，包含Electron主进程和渲染进程代码
• packages/：项目核心模块，包含SDK和各种操作器实现
• docs/：项目文档，包含详细使用说明和API参考

实战篇：环境搭建与应用运行

依赖管理与安装

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

pnpm config set registry https://registry.npmmirror.com
pnpm config set electron_mirror https://npmmirror.com/mirrors/electron/

安装项目所有依赖：

pnpm install  # 自动处理workspace依赖关系
pnpm run build:deps  # 预构建依赖包，加速后续开发

[!TIP] 为什么需要预构建？大型项目中部分依赖需要编译原生模块，预构建可避免重复编译

开发调试模式启动

启动Electron开发服务器（支持热重载）：

cd apps/ui-tars
pnpm run dev  # 普通开发模式
# 或使用调试模式（带源码映射）
pnpm run debug

成功启动后，将看到UI-TARS Desktop的欢迎界面，提供本地计算机控制和浏览器控制两种模式：

生产版本构建

执行全量构建命令生成安装包：

pnpm run build  # 执行清理、类型检查、编译和打包流程

构建产物位于out/目录，不同操作系统对应不同格式的安装包：

• Windows：UI TARS Setup x.y.z.exe
• macOS：UI TARS-x.y.z.dmg
• Linux：ui-tars_x.y.z_amd64.deb

配置篇：系统权限与环境优化

macOS系统配置

1. 将应用拖入应用程序目录完成安装：

2. 开启必要系统权限（系统设置→隐私与安全性）：

需要开启的权限：

• 辅助功能：允许UI-TARS控制鼠标和键盘
• 屏幕录制：支持界面视觉分析功能

Windows系统配置

双击安装包，出现安全提示时点击"仍要运行"：

[!TIP] Windows Defender可能会阻止未签名应用，点击"更多信息"→"仍要运行"即可继续安装

排障篇：常见问题解决方案

依赖安装问题

问题：ERROR: Cannot install in Homebrew on ARM processor
解决方案：安装Rosetta 2兼容层

softwareupdate --install-rosetta

问题：gyp: No Xcode or CLT version detected!
解决方案：安装Xcode命令行工具

xcode-select --install

运行时问题

问题：应用启动后白屏
检查点：验证apps/ui-tars/electron.vite.config.ts中入口配置是否正确，确保main.entry指向src/main/index.ts

问题：操作无响应
检查点：确认所有隐私权限已开启，参考官方文档：docs/setting.md

新手常见误区

1. 版本不匹配：使用Node.js v18或更低版本导致依赖安装失败
2. 镜像配置错误：未配置electron_mirror导致Electron下载缓慢或失败
3. 权限忽略：跳过权限设置导致应用无法正常控制鼠标和键盘
4. 直接使用npm：未使用pnpm导致依赖解析错误
5. 缺少预构建步骤：直接运行pnpm run dev而未执行pnpm run build:deps

学习路径图

环境搭建 ➜ 开发调试 ➜ 功能测试 ➜ 生产构建 ➜ 权限配置 ➜ 高级开发
  ↓           ↓           ↓           ↓           ↓           ↓
依赖安装   热重载调试   E2E测试    多平台打包   安全设置   插件开发

进阶学习树

• 核心技术
  • Electron主进程与渲染进程通信
  • TypeScript高级类型系统
  • 视觉语言模型交互原理
• 扩展方向
  • 自定义操作器开发 packages/ui-tars/operators/
  • 模型优化与定制 multimodal/agent-tars/core/
  • 插件系统开发 packages/ui-tars/sdk/

通过本指南，你已经掌握了UI-TARS-desktop开发环境的搭建方法。如需深入学习，可参考项目中的示例代码和官方文档，开始你的智能桌面助手开发之旅！