从零开始搭建UI-TARS-desktop开源项目开发环境：新手实战教程

2026-03-13 03:24:27作者：薛曦旖Francesca

UI-TARS-desktop是一款基于视觉语言模型的GUI智能助手，允许用户通过自然语言控制计算机。本教程将带你从零开始构建开发环境，掌握开源项目从源码到运行的全过程，轻松应对各类部署挑战。

一、开发环境基石构建：从零开始的系统准备

验证Node.js环境

Node.js是UI-TARS-desktop运行的基础，就像盖房子需要地基一样重要。我们需要确保安装的Node.js版本符合项目要求。

**操作步骤**：
1. 打开终端
2. 输入以下命令检查Node.js版本：
```bash
node -v  # 显示当前Node.js版本

确认输出为v20.x.x版本（LTS长期支持版）

作用解析：
此命令用于验证Node.js是否已安装及版本是否符合要求。UI-TARS-desktop基于Electron构建，需要特定版本的Node.js才能正常工作。

失败处理：

若未安装Node.js：访问Node.js官网下载v20系列LTS版本

若版本不符：使用nvm（Node版本管理器）切换版本：

nvm install 20  # 安装v20版本
nvm use 20      # 切换到v20版本


### 安装系统依赖工具

不同操作系统需要安装相应的系统依赖，这就像不同型号的汽车需要不同规格的燃料。

| 操作系统 | 安装命令 | 作用说明 |
|---------|---------|---------|
| Ubuntu/Debian | `sudo apt-get install build-essential libx11-dev libxkbfile-dev` | 安装基础编译工具和X11相关库 |
| macOS | `xcode-select --install` | 安装Xcode命令行工具，包含编译所需的基础组件 |
| Windows | 下载并安装[Visual Studio构建工具](https://visualstudio.microsoft.com/zh-hans/downloads/) | 提供Windows平台的C++编译环境 |

> [!TIP]
> **小贴士**：在Ubuntu系统中，如果安装过程提示依赖冲突，可以使用`sudo apt-get -f install`命令修复依赖关系。

### 环境诊断与修复

项目提供了一键环境诊断脚本，可以像体检一样全面检查你的开发环境是否满足要求。

```mermaid
graph TD
    A[运行诊断脚本] --> B{检查Node.js版本}
    B -->|符合要求| C[检查pnpm版本]
    B -->|不符合| D[提示安装/切换Node.js]
    C -->|符合要求| E[检查系统依赖]
    C -->|不符合| F[提示安装pnpm]
    E -->|全部通过| G[环境准备完成]
    E -->|部分缺失| H[自动安装缺失依赖]

**操作步骤**：
1. 后续步骤克隆仓库后，在项目根目录执行：
```bash
pnpm run diagnose  # 运行环境诊断脚本

作用解析：
该脚本会自动检查Node.js版本、pnpm版本、系统依赖、环境变量等关键配置，确保开发环境符合项目要求。

失败处理：

脚本会给出具体的错误信息和修复建议
对于可自动修复的问题，脚本会询问是否自动修复
对于无法自动修复的问题，会提供详细的手动修复步骤


#### 自测清单
- [ ] 已验证Node.js版本为v20.x.x
- [ ] 已安装对应操作系统的系统依赖
- [ ] 已成功运行环境诊断脚本并修复所有问题
- [ ] 了解如何切换Node.js版本

---

## 二、源码获取与项目结构解析：实战入门

### 克隆项目源码

获取项目源码是开发的第一步，就像厨师需要先准备好食材才能烹饪。

```card
**操作步骤**：
1. 打开终端，导航到你想存放项目的目录
2. 执行克隆命令：
```bash
git clone https://gitcode.com/GitHub_Trending/ui/UI-TARS-desktop.git  # 克隆仓库
cd UI-TARS-desktop  # 进入项目目录

作用解析：
git clone命令从远程仓库复制项目源码到本地，cd命令进入项目目录，为后续操作做准备。

失败处理：

若克隆速度慢：检查网络连接或尝试使用SSH协议
若克隆失败：确认仓库地址是否正确，或稍后再试


### 解析项目目录结构

了解项目目录结构有助于你快速定位所需文件，就像熟悉商场布局能让你更快找到目标店铺。

```mermaid
graph TD
    A[UI-TARS-desktop] --> B[apps]
    A --> C[packages]
    A --> D[docs]
    A --> E[examples]
    B --> F[ui-tars]  # 主应用代码
    C --> G[agent-infra]  # 代理基础设施
    C --> H[common]  # 通用工具
    C --> I[ui-tars]  # UI相关包
    D --> J[开发文档]
    E --> K[使用示例]

核心目录说明：

apps/ui-tars: 主应用代码，包含Electron主进程、渲染进程和预加载脚本
packages/: 项目依赖包，包含各种工具和组件
docs/: 项目文档，包含使用指南和开发文档
examples/: 使用示例，展示如何使用项目功能

[!TIP] 小贴士：对于大型项目，花时间熟悉目录结构是值得的，这将大大提高后续开发效率。可以使用tree命令生成目录结构树：tree -L 2（-L 2表示只显示两级目录）

创建开发分支

为了不影响主分支的稳定性，建议创建并切换到开发分支进行修改，这就像在副本上工作，不会影响原件。

**操作步骤**：
1. 在项目目录下执行：
```bash
git checkout -b feature/your-feature-name  # 创建并切换到新分支

其中your-feature-name替换为你的功能名称，例如feature/add-login

作用解析：
git checkout -b命令创建新分支并立即切换到该分支，确保你的修改不会直接影响主分支。

失败处理：

若分支已存在：使用git checkout feature/your-feature-name直接切换
若需要基于最新主分支创建：先执行git pull origin main拉取最新代码


#### 自测清单
- [ ] 已成功克隆项目源码
- [ ] 了解项目主要目录的作用
- [ ] 已创建并切换到开发分支
- [ ] 能够使用git命令进行基本操作

---

## 三、依赖管理与应用启动：实战指南

### 安装包管理器

pnpm是项目推荐的包管理器，就像给软件安装了一个智能管家，帮你高效管理依赖。

```card
**操作步骤**：
1. 安装pnpm：
```bash
npm install -g pnpm  # 全局安装pnpm
pnpm -v  # 验证安装是否成功，预期输出9.10.0及以上版本

作用解析：
npm install -g pnpm命令全局安装pnpm包管理器，pnpm -v验证安装是否成功及版本是否符合要求。

失败处理：

若安装权限不足：在命令前添加sudo（Linux/macOS）或使用管理员权限打开命令提示符（Windows）
若版本过低：执行pnpm add -g pnpm更新到最新版本


### 配置镜像加速

配置国内镜像源可以大幅提高依赖下载速度，就像给软件安装了高速通道。

```card
**操作步骤**：
1. 配置pnpm镜像：
```bash
pnpm config set registry https://registry.npmmirror.com  # 设置npm镜像
pnpm config set electron_mirror https://npmmirror.com/mirrors/electron/  # 设置electron镜像

作用解析：
这些命令将pnpm的默认仓库地址替换为国内镜像，加速依赖下载。

失败处理：

若镜像配置错误：使用pnpm config delete registry清除配置后重新设置
若镜像不可用：尝试其他镜像源，如https://registry.npm.taobao.org


### 安装项目依赖

安装项目依赖是启动应用前的关键步骤，就像给汽车加满油才能行驶。

```card
**操作步骤**：
1. 在项目根目录执行：
```bash
pnpm install  # 安装所有项目依赖

作用解析：
pnpm install命令会根据项目根目录下的package.json和pnpm-lock.yaml文件安装所有必要的依赖包。

失败处理：

若安装超时：增加超时时间pnpm install --timeout 120000
若依赖冲突：尝试pnpm install --force强制安装，或删除node_modules目录后重试


### 预构建核心依赖

预构建核心依赖可以确保后续开发和构建顺利进行，就像提前预热发动机。

```card
**操作步骤**：
1. 执行预构建命令：
```bash
pnpm run build:deps  # 预构建核心依赖包

作用解析：
此命令会预构建项目中的核心依赖包，特别是那些需要编译的原生模块，避免在启动或构建时出现编译错误。

失败处理：

若构建失败：检查系统依赖是否安装完整，特别是编译工具链
参考错误信息，安装缺失的系统库或开发文件


### 启动开发调试模式

启动开发调试模式，以热重载方式运行应用，方便实时开发和测试。

[![UI-TARS应用启动界面](https://raw.gitcode.com/GitHub_Trending/ui/UI-TARS-desktop/raw/de904997f984be2d4bc3afe516dd917adacc156e/apps/ui-tars/images/quick_start/start_button.png?utm_source=gitcode_repo_files)](https://gitcode.com/GitHub_Trending/ui/UI-TARS-desktop?utm_source=gitcode_repo_files)

```card
**操作步骤**：
1. 进入主应用目录：
```bash
cd apps/ui-tars  # 进入主应用目录
pnpm run dev  # 启动开发模式

作用解析：
pnpm run dev命令启动Electron开发服务器，以调试模式运行应用，支持代码热重载，修改代码后无需重启即可看到效果。

失败处理：

若启动白屏：检查electron.vite.config.ts配置是否正确
若控制台报错：根据错误信息修复相应问题，通常是依赖缺失或代码错误
若端口占用：修改配置文件中的端口号，或关闭占用端口的进程


#### 自测清单
- [ ] 已安装pnpm并验证版本
- [ ] 已配置镜像加速
- [ ] 已成功安装项目依赖
- [ ] 已预构建核心依赖
- [ ] 已成功启动开发调试模式

---

## 四、权限配置与问题排查：实战攻坚

### 配置系统权限

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

[![macOS权限设置界面](https://raw.gitcode.com/GitHub_Trending/ui/UI-TARS-desktop/raw/de904997f984be2d4bc3afe516dd917adacc156e/apps/ui-tars/images/mac_permission.png?utm_source=gitcode_repo_files)](https://gitcode.com/GitHub_Trending/ui/UI-TARS-desktop?utm_source=gitcode_repo_files)

```card
**操作步骤（macOS）**：
1. 打开"系统设置" → "隐私与安全性"
2. 在"辅助功能"中找到并勾选"UI-TARS"
3. 在"屏幕录制"中找到并勾选"UI-TARS"
4. 重启应用使权限生效

**操作步骤（Windows）**：
1. 当应用首次启动时，会弹出权限请求对话框
2. 点击"允许"授予所需权限
3. 如未弹出对话框，可在"设置" → "隐私和安全性"中手动配置

**作用解析**：  
这些权限允许UI-TARS-desktop控制计算机、录制屏幕，这是实现自然语言控制功能的基础。

**失败处理**：  
- 若权限未生效：尝试重启应用或重启电脑
- 若找不到应用：点击"+"按钮，手动添加UI-TARS应用程序

使用应用功能

成功启动应用后，你可以开始使用UI-TARS-desktop的核心功能。

**基本操作步骤**：
1. 在欢迎界面选择"Use Local Computer"或"Use Local Browser"
2. 在输入框中输入自然语言指令，例如"打开浏览器并搜索天气"
3. 观察应用如何执行你的指令

**作用解析**：  
UI-TARS-desktop基于视觉语言模型，能够理解自然语言指令并控制计算机执行相应操作。

**失败处理**：  
- 若指令未执行：检查网络连接，某些功能可能需要联网
- 若识别错误：尝试使用更清晰、更简洁的指令
- 若应用无响应：在终端按Ctrl+C停止开发服务器，然后重新启动

常见故障排查

遇到问题时，系统的排查方法能帮助你快速定位并解决问题。

graph TD
    A[问题发生] --> B{问题类型}
    B -->|依赖安装失败| C[检查Node.js和pnpm版本]
    B -->|编译报错| D[检查系统构建工具]
    B -->|应用启动白屏| E[检查配置文件和依赖]
    B -->|权限问题| F[检查系统权限设置]
    B -->|功能异常| G[检查网络连接和日志]
    C --> H[修复版本问题]
    D --> I[安装缺失的构建工具]
    E --> J[验证配置并重新安装依赖]
    F --> K[重新配置系统权限]
    G --> L[查看日志并排查网络]
    H --> M[问题解决]
    I --> M
    J --> M
    K --> M
    L --> M

常见问题及解决方法：

故障现象	排查路径	解决指令
依赖安装失败	检查Node.js版本和pnpm版本	`nvm install 20 && nvm use 20`
编译报错node-gyp	检查系统构建工具	`xcode-select --install` (macOS) 或安装Visual Studio构建工具(Windows)
应用启动白屏	检查入口配置	验证`electron.vite.config.ts`文件
权限不足	检查系统权限设置	参考权限配置步骤
镜像拉取缓慢	检查镜像配置	`pnpm config set registry https://registry.npmmirror.com`