桌面客户端

安装

桌面客户端是一个原生应用，提供 Windows、macOS（Apple Silicon）和 Linux 版本。 Windows、macOS 和 Linux 安装程序还捆绑了 uversion CLI 并使其可用。 请从 /downloads 下载。

Windows

下载 uVersion_x.y.z_x64-setup.exe（已签名的 NSIS 安装程序，约 25 MB）。 启动后，安装程序会：

• 将客户端安装到 %LOCALAPPDATA%\uVersion（按用户安装，无需管理员权限）
• 将安装目录添加到用户 PATH（uversion.exe CLI 已捆绑于此）
• 在开始菜单创建快捷方式
• 启用通过 Tauri updater 的自动更新

Windows 批量部署：MSI

若要用资产管理工具（Intune、SCCM、组策略等）在大量机器上部署，请使用 MSI 而非 NSIS 安装程序： uVersion_latest_x64_en-US.msi （稳定 URL，始终是最新版本，约 10 MB）。静默、按机器安装：

msiexec /i uVersion_latest_x64_en-US.msi /qn /norestart

• 安装到 C:\Program Files\uVersion（需要管理员权限）。 uversion.exe CLI 包含在内，但该目录不会被添加到 PATH：如果你的用户需要在终端使用它，请让部署工具来添加。
• MSI 安装没有自动更新：客户端会停留在已部署的版本， 批量更新通过重新部署下一个 MSI 来完成。这是有意为之： 内置更新程序会在受管副本旁边按用户安装第二份副本。
• 静默卸载：msiexec /x uVersion_latest_x64_en-US.msi /qn

首次启动时，每位用户输入服务器地址并校验证书指纹，每位用户每台机器仅需一次 （参见 TLS 指纹）。

macOS（Apple Silicon）

下载 uVersion_x.y.z_macos-arm64.app.zip（约 32 MB，已用 Developer ID 签名并经 Apple 公证）。双击解压，然后将 uVersion.app 拖入 /Applications。 首次启动时，Gatekeeper 会自动校验公证，不会有任何警告。

uversion CLI 已捆绑在应用内。首次启动时，客户端会自动创建一个指向 ~/.local/bin/uversion 的符号链接，并通过 ~/.zprofile 将 ~/.local/bin 添加到你的 PATH：无需手动操作。打开一个新的终端，uversion 即可使用。

注意：仅支持 Apple Silicon（M1/M2/M3/M4）。没有 Intel 二进制文件。

Linux

x86_64 只有一种格式：AppImage （uVersion_x.y.z_amd64.AppImage，约 85 MB）。它是便携的，捆绑了自身依赖 （libwebkit2gtk、libgtk、libsoup 等），无需系统级安装即可在任何较新的发行版上运行。 前提条件：Ubuntu 24.04 或更高、Debian 13 或更高，或同代的发行版。二进制文件需要较新的系统 C 库，而 AppImage 并不会降低这一门槛：它捆绑的是图形环境，而不是 C 库。

推荐的方式是安装脚本。无需 sudo：

curl -fSL https://uversion.io/downloads/client/install.sh | sh

它不会做任何魔法般的事，尤其不会做任何需要权限的事：

• 它拒绝以 root 运行、在非 x86_64 架构上运行，或在过旧、无法执行该二进制文件的系统上运行， 并会告诉你三者中哪一个有问题；
• 它将 AppImage 下载到 ~/Applications/uVersion.AppImage，并检查下载到的确实是一个 Linux 可执行文件（否则强制门户页或错误页会被保存并被赋予可执行权限，从而在稍后以令人费解的方式失败），随后以一步 到位的方式放置它，即使已有一份副本在运行也依然安全；
• 它会启动应用程序。正是这次启动创建了应用程序菜单中的条目，因此最好让它执行。在没有图形界面的远程会话中， 它会转而显示你应从自己桌面上输入的准确命令。

你也可以从下载页面手动下载 AppImage，赋予其可执行权限并运行：

chmod +x uVersion_x.y.z_amd64.AppImage
./uVersion_x.y.z_amd64.AppImage

客户端没有 .deb 软件包，将来也不会有：由 dpkg 安装的软件包只能再次经由 dpkg 更新，因而每个版本都要提权，而这对没有管理员权限的机器来说是不可能的。AppImage 无需密码即可 自我替换。而服务器则仍然保留其 .deb 软件包。

注意：uversion CLI 已捆绑在 AppImage 内。首次启动时，客户端会将二进制文件复制到 ~/.local/bin/uversion，并通过 ~/.profile 将 ~/.local/bin 添加到你的 PATH（无需手动操作）。出于同样的原因，应用程序菜单条目也在首次启动时创建：AppImage 是一个文件，而不是一次安装。

首次启动

1. 填写服务器地址和你的凭据

首次启动时，客户端会显示标题为 Welcome to uVersion 的登录页。 Server address 字段并不期待一个完整的 URL：它被拆成三块，一个不可修改的 https:// 前缀、主机，以及端口（默认 8443）。协议是固定的，客户端无法生成 http://。 在主机框中粘贴完整地址或 host:port，会自动把它分配到两个字段中。随后填写 Username 和 Password，再点击 Sign in。

2. 校验服务器指纹，仅需一次

由于 uVersion 服务器默认是自签名的，首次连接到某台机器时会显示 Verify server identity： 将 SHA-256 指纹与管理员给你的进行比对，然后点击 Trust this server。这个问题每台服务器只会问一次， 如果它在红色标题 Server identity changed 下再次出现，说明指纹变了：不要在未核实的情况下接受。 参见 TLS 指纹。

连接之后，客户端会安全地记住你的会话。uversion CLI 和编辑器插件（Unreal、Rider）会自动复用同一套凭据： 你无需在其他任何地方重新输入密码。

打开或克隆仓库

登录不会打开任何项目：仓库列表需要显式请求。同一个窗口既用于首次克隆一个项目，也用于重新打开一个已在磁盘上的工作区。

1. 打开 Open Repository 窗口

只要没有任何标签页打开，Workspace 就会显示 No repository selected 和一个 Open Repository 按钮。一旦你至少有了一个标签页，就可以通过标签栏的 + 打开同一个界面。 该窗口以每个项目一张卡片的形式，列出你有权访问的仓库，并带有一个 Refresh 按钮，用于向服务器重新请求列表。

2. 克隆，或重新打开一个已有的工作区

每张卡片都会提供与其状态相符的操作：

• Clone：创建一个全新的工作区。卡片的 Workspace name 字段会命名所创建的 文件夹，若留空则沿用项目名称。随后的文件夹选择器会询问父文件夹：子文件夹由 uVersion 自己创建。
• Clone New：同一个按钮，当该项目已存在一个工作区时会改名。再克隆一次是合理的，例如为了将 项目的两种状态并排保留。
• Open：重新打开一个已在本机克隆过的工作区，其路径会在卡片下方提示。当该标签页已经打开时， 此处会改为显示 Switch to Open Tab。
• Open Local Repository...（窗口底部）：指向一个已包含 .uversion/ 的文件夹， 例如在移动过一个工作区之后。

底部的 Download files after clone 复选框默认勾选，会在克隆之后紧接着开始下载。取消勾选，可以现在就 创建工作区，稍后再取回文件。

3. 跟踪下载

克隆一开始，窗口就会关闭，这是有意为之：传输可能持续数小时，不应把你卡住。进度会在客户端头部继续， 工作区标签页会在结束时自动打开，而且网络中断不会丢失任何东西，因为传输会自行恢复。

Workspace

工作区是一个链接到服务器仓库的本地文件夹。客户端可以同时管理多个工作区，显示在顶部的标签栏中。每个工作区 把自己的元数据存放在本地文件夹根部的 .uversion/ 中：

• .uversion/config.toml：唯一真正重要的文件。它的 [workspace] 段承载工作区的所有者 （owner）、其标识符、其名称，以及 last_synced_revision，即你已同步到的修订版 （没有 .last_sync 文件）。Unreal 引擎路径也记录在这里。
• .uversion/checkouts_<workspace_id>.json：你在这个工作区中持有的锁
• .uversion/changelists_<workspace_id>.json：你的 changelist，也就是你为了分别提交而归拢在 一起的一批已检出文件。纯本地，从不传给服务器。
• .uversion/pending_deletes_<workspace_id>.json：等待提交的删除
• .uversion/snapshots.json：已知的文件状态，用于识别你在本地做了哪些改动

Files 标签页

以树状视图展示工作区文件及其状态。有两种方式缩小列表：

• 搜索框（标注为 Search files...）：按路径的一部分过滤，不区分大小写。
• 状态标签，就在下方。它们是可点击的计数器，而且 只有当计数器大于零时，标签才会出现：在一个刚刚同步过的工作区上，你只会看到 {n} synced， 其他标签不出现是正常的。六个可能的标签是 {n} synced、{n} modified、{n} local only、 {n} server only、{n} locked 和 {n} deleted。

搜索与标签可以组合：搜索先缩小范围，标签再进一步过滤。 即便是数万个文件规模的项目，视图也依然流畅。

多选 + 操作

只有在选中了内容时，操作栏才会存在。只要选择为空，就没有任何按钮：这是正常的，并不是正在加载。 选中一些文件（点击 + shift，或勾选框），操作栏便会出现，并以所选数量作为前缀（{n} file(s) selected）。 按钮会根据所选内容允许什么而显示：

按钮	作用
History	打开所指文件或文件夹的历史。
Add	把一个 local only 文件纳入跟踪。它是首次提交两个按钮中的第一个：你刚创建的文件在服务器端并不存在，所以没有什么可锁的。
Checkout	获取锁。幂等：对一个已由你锁定的文件再次锁定不会有任何效果。
Checkin	打开消息窗口，然后提交。它是首次提交的第二个按钮，也是之后每一次提交所用的按钮。
Revert	交回锁并恢复服务器版本。你的本地改动将丢失。
Delete	将文件标记为已删除。删除会在下一次 checkin 时发出。
Download	从服务器重新下载所选文件，适合用来找回本地损坏的文件。

Pending 标签页

当前已检出、由你或另一位用户锁定的文件。分为两个区块：

• Your locks：你可以逐个 checkin、revert 或 release
• Other users' locks：你能看到谁持有该锁，还有一个 Request release 按钮，会在 Production 看板中创建一张请求卡片（带 request 徽章）

管理员还会在他人的锁上看到 Force unlock 按钮，它会在未经持有者同意的情况下 release 该锁。所有 force unlock 都会被审计。

History 标签页

分页列出仓库的提交，含作者、日期、消息和已更改的文件。 点击某个提交会打开详情：该提交全部文件及其修订版的完整列表。

每个提交上的 Get all 按钮可下载该修订版下所有文件的本地副本（用于找回一个稳定状态很方便）。

Production

Production 区域（侧边栏中的专用入口）按仓库汇集项目跟踪。 而 Workspace 则专注于文件（Files、Pending、History）。

My tasks

分配给你的卡片列表，跨你有权访问的所有仓库进行汇总。

Board

按仓库划分的看板，列可配置（默认 To Do、In Progress、Review、Done）。每张卡片带有优先级 （low / normal / high / urgent）、标签、指派人、截止日期、 评论、指向资产或提交的链接，以及一张封面图。

Dashboard

制作人的驾驶舱：一条项目健康横幅（未解决的阻塞项、待处理的 playtest 报告）、问题集中的区域、本周提交、项目体量 以及最后发布的构建，每个区块都链接到看板或 Games。

在其下方是日历时间线：里程碑、playtest（一次性或重复）、发布以及卡片截止日期。 一个重复的 playtest 会在每次发生时自动生成它的看板卡片。

Watchlist

监视一些路径（glob 模式），以便在触及它们的 check-in 发生时收到通知。每一项都会指明被监视的路径以及所跟踪的事件。

Games

Games 区域列出为该项目发布的内部 playtest 构建。 每个构建会标明其版本、配置（DebugGame / Development / Shipping）、平台（Win64 / Mac / Linux）、大小和发布说明， 并带有与平台匹配的下载按钮。

这是 playtester 的访问入口：一个拥有 playtester 角色的账户只能看到这个页面 （既看不到 Workspace 也看不到 Production），且只能访问对其开放的项目的构建。

本地 Changelist

📷 Screenshot · client-changelists

已检出的文件被分到两个本地 changelist 中（例如「default」和「review」）。

把你已检出的文件归拢为多个相互独立的提交。changelist 是你工作区的本地概念（从不发送到服务器）。用于：

• 把一个关键修复与进行中的工作分开
• 不把一切混在一起地并行准备多次提交
• 保留一个用于 WIP 的「default」changelist，和一个用于要 checkin 内容的「review」

Settings

客户端的全局偏好（保存在 %APPDATA%/uversion/uVersion/config/config.toml）：

设置	说明
Default Server address	预填登录页。与连接时相同的拆分：固定的 https:// 前缀、主机、端口。可以留空。
Default Username	预填登录页。
Default Repository Path	克隆时默认建议的文件夹。
Theme	System / Light / Dark。
Show hidden files	在 Files 标签页中显示以 . 开头的文件。
Auto-sync Interval (seconds)	是一个数值字段，而不是下拉列表，以秒而非分钟表示。最小为 0，且 0 会禁用自动同步。
Parallel Uploads	并发上传数，从 1 到 32。
Parallel Downloads	并发下载数，从 1 到 32。
Avatar colour	你在界面中的颜色（看板卡片、锁、活动上的首字母）。与其他设置不同，此设置保存在服务器端：它会随你从一台机器到另一台机器，你的队友也能看到。

Unreal 面板

当客户端在工作区中检测到 Unreal 项目时，Workspace 右上角会出现一条专用操作栏。它直接从客户端驱动引擎：打开编辑器、编译、 打包，无需经过 IDE。大多数操作只针对 C++ 项目（纯 Blueprint 项目无需编译）。

插件状态圆标

在栏的最左端，有一个圆标指示该项目的 Unreal 插件处于什么状态。它可点击：

圆标	含义
Plugin <version>（绿色）	插件已安装，且对你的 Unreal 版本而言是最新的。
Plugin installed（绿色）	插件刚被放入项目。
Update ready（橙色）	存在更新的版本。客户端不会自行安装：请关闭 Unreal，然后点击圆标。
Restart UE（橙色）	Unreal 编辑器正开着。已加载的插件无法替换：请关闭编辑器再点击。
Set engine path（橙色）	缺少引擎路径。点击会直接打开路径选择器。
Plugin n/a（橙色）	对于这一 Unreal 版本与系统的组合，没有发布任何二进制文件。

引擎路径

Unreal 的安装路径会依据 .uproject 的 EngineAssociation 自动解析（Windows 注册表、 LauncherInstalled.dat，或源码构建）。以下所有操作都需要这个路径，而自动解析尤其会在从源码编译的引擎上失败。 下面是手动设置它的地方。

1. 打开次级操作菜单

栏里既没有输入框，也没有 Browse 按钮，更没有 Auto-detect 按钮可见。唯一的入口是 Unreal 栏最右端的齿轮形按钮，旁边带一个小箭头，其提示写着 More actions。它的外观丝毫不提及引擎， 正因如此才找不到它。

2. 选择 Set Engine Path...

Set Engine Path... 是菜单中的最后一项。它的副标题显示当前路径，若没有则显示 Not configured：这是判断问题是否出在此处的最快方式。会打开一个文件夹选择器，所选路径会保存到工作区的 .uversion/config.toml 中。

Open Editor

在工作区项目上启动 Unreal 编辑器（UnrealEditor）。该按钮是幂等的：编辑器可能要花上数十秒才会 显示窗口（尤其在 macOS / Linux 上），因此在此期间的第二次点击不会打开第二个实例。编辑器启动期间，按钮会显示「Opening…」。 对于一个从未在本地编译过的 C++ 项目，打开编辑器会先触发一次项目文件生成，然后是一次编译 （参见自动操作）。

Compile

编译项目（Unreal Build Tool）。输出会在一个集成控制台中实时显示。一个 C++ 项目必须先编译，编辑器才能打开它，也才能反映 代码改动。

Sync 与 Status

这两个按钮位于同一条栏中，而不在 Files 标签页里：

• Sync：从服务器更新整个工作区。当有待处理文件时，它的提示会标出其数量。这才是客户端真正的 「sync」，不要与只取回所选内容的 Files 标签页 Download 按钮混淆。
• Status：刷新服务器端的状态，包括其他用户的锁，并重新更新 Sync 按钮的计数。

More actions 菜单

更少用的操作被归到栏右侧的齿轮形按钮之后（见上方截图）：

• Generate Project Files：重新生成 IDE 的项目文件（Visual Studio、Rider）。在添加或删除 源文件之后，或克隆之后很有用。
• Publish Editor Binaries：先编译，然后发布对应于最新代码提交的编辑器二进制文件。你的队友会 在 sync 时取得它们，而不必各自重新编译。Linux 上不提供。
• Force Sync：重新下载并覆盖你的本地文件。在菜单中以红色标示，附有 overwrites local 字样，并会先经过一次确认。请只用于你可以接受丢失的工作区。
• Set Engine Path...：上文所述的引擎路径设置。

Package

这个按钮叫 Package；「Package Game」只是它的提示，当引擎路径缺失时会被替换为 Set Engine Path first，此时按钮被禁用。它通过 RunUAT BuildCookRun 打包游戏，并把结果归档到 工作区根部的 Packages/{config}/。有三种配置可选：

配置	用途
DebugGame	调试构建（完整符号，未优化）。
Development	开发构建（默认）：已优化但带开发工具。
Shipping	发行构建：已优化，不带开发工具。

Packages/ 文件夹默认被忽略（.uversionignore）：打好包的东西不做版本管理， 它们通过 Publish Build 分发。

Publish Build

把一个打好包的构建作为内部 playtest 版本发布。它会变得可供你的团队从客户端的 Games 页面下载 （playtester 角色或已获授予构建访问权）。客户端会扫描 Packages/{config}/，上传文件 （在服务器端去重）然后登记清单。

Open project folder

在系统文件资源管理器中打开工作区文件夹（Windows 资源管理器、Finder，或 Linux 上的 xdg-open）。

Stop

干净地中断所有正在进行的构建：编译和打包。按钮会标出停止了多少个构建（后台启动的一次自动编译 可能会一并计入）。

自动操作

除了这些按钮，客户端还会自行触发某些 Unreal 操作，以让一个 C++ 项目始终保持最新且可编译：

• 在 check-in 之前：如果代码文件有改动，会先编译项目。如果编译失败，check-in 会被阻止（不提交无法编译的 代码）。
• 在 sync 之后：如果 sync 下载了代码，客户端会重新生成项目文件然后重新编译。
• 克隆后的首次启动（C++ 项目）：在能打开编辑器之前，先生成项目文件然后编译。

这些自动构建会在引擎锁（Unreal Build Tool -WaitMutex）上串行化：它们不会相互拒绝，而是依次排队。 Stop 按钮同样会中断它们。