3个步骤搞定UI-TARS-desktop开发环境搭建：源码编译到运行全攻略
【免费下载链接】UI-TARS-desktopA GUI Agent application based on UI-TARS(Vision-Lanuage Model) that allows you to control your computer using natural language.项目地址: https://gitcode.com/GitHub_Trending/ui/UI-TARS-desktop
想体验用自然语言控制电脑的黑科技吗？UI-TARS-desktop是一款基于视觉语言模型的GUI智能助手，能帮你通过文字指令完成各种电脑操作。本文将带你从零开始，用3个步骤完成开发环境搭建，包括源码编译、环境配置和运行调试，即使是技术小白也能轻松上手。
需求定位：你需要这款工具吗？
如果你符合以下任一情况，那这篇指南就是为你准备的：
- 想开发能理解屏幕内容的AI助手
- 希望通过自然语言控制电脑操作
- 对Electron+TypeScript跨平台开发感兴趣
- 需要本地化运行视觉语言模型应用
UI-TARS-desktop能让你告别繁琐的鼠标点击，直接用文字命令让电脑完成任务，无论是浏览器操作还是桌面应用控制，都能轻松实现。
准备工具清单：开发环境必备
核心工具安装
在开始前，请确保你的电脑已安装以下工具（版本要严格匹配哦！）：
Node.js v20.x
- 目标：提供JavaScript运行环境
- 操作：从Node.js官网下载对应系统安装包
- 验证：打开终端输入
node -v，显示v20.x.x即为成功
pnpm v9.10.0+
- 目标：高效管理项目依赖
- 操作：安装Node.js后执行
npm install -g pnpm - 验证：终端输入
pnpm -v，显示9.10.0以上版本
Git
- 目标：获取项目源码
- 操作：根据你的系统从Git官网下载安装
- 验证：终端输入
git --version，显示版本号即为成功
环境检测工具
为了确保环境配置正确，我们准备了一键检测脚本，复制以下命令到终端执行：
# 创建环境检测脚本 cat > env-check.sh << 'EOF' #!/bin/bash echo "=== UI-TARS环境检测工具 ===" node -v | grep -q "v20." && echo "✅ Node.js版本符合要求" || echo "❌ 请安装Node.js v20.x" pnpm -v | grep -q "9.10" && echo "✅ pnpm版本符合要求" || echo "❌ 请安装pnpm 9.10.0+" git --version > /dev/null && echo "✅ Git已安装" || echo "❌ 请安装Git" echo "==========================" EOF # 赋予执行权限并运行 chmod +x env-check.sh && ./env-check.sh执行后如果看到三个✅，就可以放心进入下一步啦！
实施步骤：3步搭建开发环境
步骤1：获取源码
目标：将项目代码下载到本地 操作：
# 克隆代码仓库 git clone https://gitcode.com/GitHub_Trending/ui/UI-TARS-desktop cd UI-TARS-desktop验证：执行ls命令，能看到apps、docs、packages等目录即为成功
项目结构速览：
UI-TARS-desktop/ ├─ apps/ui-tars/ # 主应用目录（重点关注） │ ├─ src/main/ # 主进程代码 │ ├─ src/renderer/ # 界面渲染代码 │ └─ images/ # 应用截图资源 ├─ docs/ # 项目文档 └─ packages/ # 核心功能模块步骤2：安装依赖
目标：一键安装所有项目依赖 操作：
# 配置国内镜像加速（可选但推荐） pnpm config set registry https://registry.npmmirror.com # 安装依赖 pnpm install验证：终端显示Packages installed successfully，且项目根目录出现node_modules文件夹
避坑小贴士：如果安装过程卡住，按Ctrl+C终止后，删除node_modules文件夹和pnpm-lock.yaml文件，重新执行pnpm install
步骤3：启动开发环境
目标：运行应用并验证功能 操作：
# 进入主应用目录 cd apps/ui-tars # 启动开发模式 pnpm run dev验证：等待编译完成后，会自动弹出应用窗口，显示UI-TARS Desktop欢迎界面
问题解决：避坑指南
依赖安装失败
点击展开解决方案
错误提示：
ERROR: Cannot install in Homebrew on ARM processor in Intel default prefix (/usr/local)解决方法：安装Rosetta 2（仅适用于Apple Silicon芯片Mac）
softwareupdate --install-rosetta编译报错node-gyp相关
点击展开解决方案
错误提示：
gyp: No Xcode or CLT version detected!解决方法：安装Xcode命令行工具（仅适用于Mac）
xcode-select --install启动后白屏
点击展开解决方案
可能原因：Vite配置错误或依赖缺失
解决方法：
- 检查是否安装了所有依赖：
pnpm install - 清除缓存后重试：
pnpm run dev -- --force - 检查配置文件：
apps/ui-tars/electron.vite.config.ts
权限配置：按模式选择
新手模式
macOS系统
- 将应用拖入应用程序文件夹：
- 开启必要权限：
- 打开"系统设置" → "隐私与安全性"
- 在"辅助功能"和"屏幕录制"中勾选UI-TARS
Windows系统
- 双击安装包，当出现SmartScreen提示时，点击"更多信息" → "仍要运行"：
- 安装过程中全部点击"下一步"即可
高级模式（适合开发者）
如果你需要修改源码并调试，可以配置额外权限：
# macOS终端命令行授权（需管理员权限） sudo sqlite3 /Library/Application\ Support/com.apple.TCC/TCC.db "INSERT INTO access VALUES('kTCCServiceAccessibility','com.yourcompany.uitars',0,1,1,NULL,NULL,NULL,'UNUSED',NULL,0,1665687402);"进阶技巧：开发提效指南
远程调试
需要在多设备上测试？使用以下命令启动远程调试模式：
pnpm run debug -- --remote-debugging-port=9222然后在另一台设备的浏览器中访问http://<你的IP>:9222，即可远程调试应用。
热重载原理
UI-TARS-desktop使用Vite的热模块替换(HMR)功能，修改代码后无需重启应用：
- 渲染进程代码（
src/renderer/）：实时更新，无刷新 - 主进程代码（
src/main/）：自动重启主进程，保持窗口状态
效率加速器：使用VSCode的Electron插件，可以直接在编辑器中设置断点调试。
推荐开发工具
- VSCode：内置TypeScript支持和调试工具
- Electron DevTools：专门用于Electron应用的调试扩展
- PNPM Workspace：高效管理多包项目依赖
总结
通过以上步骤，你已经成功搭建了UI-TARS-desktop的开发环境！现在你可以：
- 修改源码自定义功能
- 调试新的视觉语言模型
- 开发自己的自然语言指令功能
官方文档：docs/quick-start.md API接口定义：packages/ui-tars/sdk/src/index.ts 贡献指南：CONTRIBUTING.md
开始你的AI桌面助手开发之旅吧！遇到问题可以查阅项目文档或在社区寻求帮助。
【免费下载链接】UI-TARS-desktopA GUI Agent application based on UI-TARS(Vision-Lanuage Model) that allows you to control your computer using natural language.项目地址: https://gitcode.com/GitHub_Trending/ui/UI-TARS-desktop
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
