UI-TARS-desktop开发环境搭建全攻略：从零基础到应用运行

2026-04-26 11:44:49作者：贡沫苏Truman

一、环境准备：搭建开发基础平台

检查Node.js运行环境

要开发UI-TARS-desktop，首先需要确保Node.js版本符合要求。这个基于Electron+TypeScript的项目需要Node.js v20.x版本才能正常工作。

node -v  # 查看当前Node.js版本

为什么这样做？Electron框架对Node.js版本有严格依赖关系，使用不兼容版本会导致依赖安装失败或运行时错误。如果版本低于v20.x或高于v20.x，建议使用版本管理工具切换到正确版本。

💡 实用技巧：使用nvm可以轻松管理多个Node.js版本，安装命令：curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash，然后通过nvm install 20安装v20版本。

验证标准：命令输出应为v20.x.x格式，如v20.10.0。

安装pnpm包管理工具

项目采用pnpm作为包管理器，需要安装v9.10.0及以上版本。

npm install -g pnpm  # 全局安装pnpm
pnpm -v  # 验证安装版本

为什么这样做？pnpm采用内容寻址存储机制，比npm和yarn具有更快的安装速度和更小的磁盘占用。项目使用pnpm workspace管理多包依赖，必须使用pnpm才能正确解析依赖关系。

⚠️ 注意事项：如果npm安装速度慢，可以先配置国内镜像：npm config set registry https://registry.npmmirror.com

验证标准：命令输出应为9.10.0或更高版本。

二、项目获取：源码与依赖管理

获取项目源代码

使用Git工具克隆项目仓库到本地开发目录。

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

为什么这样做？这一步获取项目完整源代码，包括应用代码、配置文件和资源文件。项目采用Git版本控制，便于后续更新代码和贡献。

⚠️ 注意事项：确保网络连接稳定，克隆过程中不要中断，否则可能导致代码不完整。

验证标准：项目目录下应包含package.json、pnpm-workspace.yaml等核心配置文件。

安装项目依赖

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

pnpm install  # 安装项目依赖

为什么这样做？项目依赖众多第三方库，pnpm会根据package.json和pnpm-lock.yaml安装指定版本依赖，确保开发环境一致性。

💡 实用技巧：配置国内镜像加速依赖安装：

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

验证标准：命令执行完成无错误提示，项目根目录出现node_modules文件夹。

预构建依赖包

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

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

为什么这样做？部分依赖（如原生模块）需要在安装后进行编译构建，预构建可以提前发现和解决构建问题，避免在开发或打包时出错。

验证标准：命令执行完成无错误提示，无红色错误信息输出。

三、应用启动：开发与生产模式

启动开发调试模式

进入应用目录并启动开发服务器，以调试模式运行应用。

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

为什么这样做？开发模式支持热重载，代码修改后会自动应用，无需重启应用，极大提高开发效率。Electron会启动主进程和渲染进程，并打开应用窗口。

成功启动后，应用窗口将显示欢迎界面，提供"Computer Operator"和"Browser Operator"两种功能选项。

验证标准：应用窗口成功打开，显示欢迎界面，无报错信息。

构建生产版本

执行构建命令，生成可执行的应用安装包。

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

验证标准：构建完成后，out目录下生成对应系统的安装包文件。

四、系统配置：跨平台安装指南

macOS系统安装配置

在macOS上安装UI-TARS-desktop需要完成两个关键步骤：

配置必要系统权限：

需要开启的权限包括：

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

为什么这样做？macOS对应用权限管理严格，这些权限是UI-TARS-desktop实现GUI控制的基础，缺少权限会导致功能受限。

验证标准：应用成功安装到Applications目录，系统设置中UI-TARS的辅助功能和屏幕录制权限已开启。

Windows系统安装配置

在Windows系统上安装过程相对简单，但可能会遇到安全提示：

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

为什么这样做？由于应用未经过Microsoft签名，Windows Defender SmartScreen会发出警告，这是开源软件的常见现象，选择继续安装即可。

验证标准：应用成功安装，桌面出现UI-TARS-desktop快捷方式，双击可正常启动。

不同操作系统配置对比

配置项	Windows系统	macOS系统	Linux系统
安装方式	双击EXE文件	拖拽到Applications	安装DEB/RPM包
权限配置	无需特殊配置	需要辅助功能和屏幕录制权限	需要无障碍权限
安全提示	SmartScreen警告	未知开发者提示	软件源信任设置
快捷方式	自动创建桌面快捷方式	Launchpad中查找	应用菜单中查找
卸载方式	控制面板卸载	拖拽到废纸篓	包管理器卸载

五、问题排查：常见错误与解决方案

依赖安装问题

错误症状	可能原因	解决方案
安装失败，提示"Cannot install in Homebrew on ARM processor"	Apple Silicon芯片架构兼容性问题	安装Rosetta 2：`softwareupdate --install-rosetta`
编译报错`node-gyp`相关错误	缺少Xcode命令行工具	安装Xcode命令行工具：`xcode-select --install`
提示"pnpm: command not found"	pnpm未添加到系统PATH	检查环境变量，或使用完整路径`~/.npm-global/bin/pnpm`
依赖安装缓慢或失败	网络问题或未配置国内镜像	配置国内镜像：`pnpm config set registry https://registry.npmmirror.com`

应用启动问题

错误症状	可能原因	解决方案
应用启动白屏	入口配置错误	检查electron.vite.config.ts中`main.entry`是否指向`src/main/index.ts`
启动时报错"Cannot find module"	依赖未正确安装	删除node_modules和pnpm-lock.yaml，重新执行`pnpm install`
界面显示异常	前端资源构建失败	执行`pnpm run build:renderer`单独构建前端资源
无法启动，提示端口占用	端口被其他程序占用	查找并关闭占用端口的程序，或修改配置文件中的端口号

功能问题

错误症状	可能原因	解决方案
无法控制鼠标键盘	未开启辅助功能权限	参考系统配置章节开启相应权限
视觉识别功能失效	未授予屏幕录制权限	在系统设置中开启屏幕录制权限
模型无法加载	API密钥配置错误	检查设置中的API密钥是否正确，参考docs/setting.md