开源项目UI-TARS-desktop环境搭建新手教程：零基础从源码编译到跨平台配置全攻略

作为一款基于视觉语言模型的GUI智能助手，UI-TARS-desktop允许用户通过自然语言控制计算机。本教程将带你完成从环境预检到功能验证的全过程，掌握源码编译、依赖管理与跨平台配置技巧，即使零基础也能轻松避坑。

一、零基础环境预检：三步完成开发工具箱配置

1.1 验证Node.js环境（避坑指南）

开发UI-TARS-desktop首先需要确保Node.js环境符合要求。项目基于Electron+TypeScript构建，Node.js版本需严格匹配v20.x。

node -v  # 检查Node.js版本
# 预期输出：v20.x.x（x为具体版本号）

💡 新手提示：Node.js是运行JavaScript的环境，就像电脑需要操作系统一样，这个项目需要特定版本的Node.js才能正常工作。

⚠️ 风险预警：Electron框架对Node.js版本有严格要求，使用不兼容版本会导致依赖安装失败或运行时错误。如果版本不匹配，可从Node.js官网下载并安装v20.x版本。

✅ 验证标准：成功输出Node.js版本号，且版本为v20.x.x。

1.2 安装pnpm包管理器（避坑指南）

pnpm（新一代包管理工具，比npm安装更快）是项目推荐的包管理器，需要安装v9.10.0及以上版本。

npm install -g pnpm  # 全局安装pnpm
pnpm -v  # 验证安装结果
# 预期输出：9.10.0+（版本号大于等于9.10.0）

💡 新手提示：包管理器就像应用商店，pnpm能帮你快速下载和管理项目所需的各种"零件"。

⚠️ 风险预警：项目采用pnpm workspace管理多包依赖，必须使用pnpm才能正确安装依赖，使用npm或yarn可能导致依赖结构错误。

✅ 验证标准：成功输出pnpm版本号，且版本为9.10.0及以上。

1.3 环境一键检测脚本

项目提供了环境诊断脚本，可快速检查开发环境是否符合要求：

# 后续步骤克隆代码后在项目根目录执行
pnpm run diagnose  # 运行环境诊断工具

💡 新手提示：这个脚本会自动检查Node.js版本、pnpm版本、依赖完整性等，并提供问题修复建议，遇到环境问题时可优先使用。

二、源码获取避坑指南：零基础克隆与目录验证

2.1 克隆项目代码仓库

使用Git工具从指定仓库克隆项目源码到本地。

git clone https://gitcode.com/GitHub_Trending/ui/UI-TARS-desktop.git
cd UI-TARS-desktop  # 进入项目目录

💡 新手提示：Git是版本控制工具，克隆就像是把项目的完整副本下载到你的电脑上。

⚠️ 风险预警：确保网络连接正常，克隆过程中不要中断，否则可能导致代码不完整。如果克隆失败，可以尝试使用git clone --depth 1命令进行浅克隆。

2.2 验证项目目录结构

克隆完成后，检查项目目录是否完整：

ls -la  # 列出目录内容（Windows系统使用dir命令）

💡 新手提示：成功克隆后，你应该能看到README.md、package.json等文件，以及apps、docs、packages等文件夹。

✅ 阶段验收清单：

• 项目根目录包含package.json文件
• 存在apps/ui-tars目录（主应用代码）
• 存在pnpm-workspace.yaml文件（多包管理配置）

三、核心配置避坑指南：依赖安装与预构建

3.1 安装项目依赖

使用pnpm安装项目所有依赖，包括开发依赖和生产依赖。

pnpm install  # 安装所有依赖

💡 新手提示：这一步会根据package.json文件下载项目所需的所有"零件"，可能需要几分钟时间，请耐心等待。

⚠️ 风险预警：如果安装速度慢，可以配置国内镜像加速：

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

3.2 预构建依赖包

安装依赖后，需要预构建依赖包以确保后续开发和构建顺利进行。

pnpm run build:deps  # 预构建依赖包

💡 新手提示：有些依赖需要编译后才能使用，这一步就是提前完成这些编译工作，避免后续开发中出现意外错误。

✅ 阶段验收清单：

• node_modules文件夹被创建
• 执行过程无红色错误提示
• 命令行最后显示"build:deps completed"类似信息

四、功能验证全攻略：应用启动与系统权限配置

4.1 启动开发调试模式

启动Electron开发服务器，以调试模式运行应用，支持热重载。

cd apps/ui-tars  # 进入主应用目录
pnpm run dev  # 启动开发模式

💡 新手提示：开发模式下，你对代码的修改会实时反映到应用中，不用重启应用，非常适合边开发边测试。

成功启动后，将自动打开应用窗口，显示UI-TARS-desktop的欢迎界面，提供"Computer Operator"和"Browser Operator"两种功能选项。

4.2 系统权限配置（跨平台指南）

macOS系统权限配置：

1. 将应用拖入/Applications目录
2. 开启必要权限（系统设置→隐私与安全性）：
   • 辅助功能：允许控制鼠标键盘
   • 屏幕录制：支持界面视觉分析

💡 新手提示：macOS对应用权限管理比较严格，这些权限是UI-TARS-desktop正常工作所必需的，缺少权限会导致应用无法控制电脑或识别屏幕内容。

Windows系统权限配置：

直接双击安装包进行安装，过程中可能会遇到安全提示。

当出现"Windows已保护你的电脑"提示时，点击"仍要运行"继续安装。

💡 新手提示：由于应用未经过Microsoft签名，Windows Defender SmartScreen会发出警告，这是开源软件的常见情况，选择"仍要运行"即可。

✅ 阶段验收清单：

• 应用窗口成功打开，显示欢迎界面
• 无报错信息或异常弹窗
• 系统权限已正确配置

五、问题攻坚：故障速查表与解决方案

5.1 常见故障速查表

🔧 依赖安装失败

• 症状：提示"Cannot install in Homebrew on ARM processor"
• 原因：Apple Silicon芯片架构兼容性问题
• 解决方案：安装Rosetta 2：softwareupdate --install-rosetta

🔧 编译报错

• 症状：node-gyp相关错误，提示"No Xcode or CLT version detected"
• 原因：缺少Xcode命令行工具
• 解决方案：安装Xcode命令行工具：xcode-select --install

🔧 应用启动白屏

• 症状：应用窗口打开后显示空白页面
• 原因：入口配置错误
• 解决方案：检查electron.vite.config.ts中main.entry是否指向src/main/index.ts

🔧 权限不足

• 症状：操作时提示"权限不足"或功能无响应
• 原因：未开启必要系统权限
• 解决方案：参考官方权限文档：docs/setting.md

🔧 镜像拉取缓慢

• 症状：依赖下载速度慢或超时
• 原因：网络问题或未配置国内镜像
• 解决方案：配置国内镜像：pnpm config set electron_mirror https://npmmirror.com/mirrors/electron/

5.2 从搭建到开发的学习路线图

1. 环境巩固

   • 熟悉pnpm命令：pnpm help查看常用命令
   • 学习Electron基础：了解主进程与渲染进程概念

2. 源码探索

   • 应用入口：apps/ui-tars/src/main/main.ts
   • UI组件：apps/ui-tars/src/renderer/src/components

3. 功能开发

   • 参考示例：examples/目录下的示例代码
   • API文档：packages/ui-tars/sdk/src/index.ts

4. 贡献代码

   • 阅读贡献指南：CONTRIBUTING.md
   • 提交PR：遵循项目代码规范和提交信息格式

通过本教程，你已经成功搭建了UI-TARS-desktop的开发环境并运行了应用。接下来，你可以开始探索项目源码，尝试修改或添加新功能，开启你的开源贡献之旅！