Wiki

桌面客户端

适用于 Windows、macOS 和 Linux 的 uVersion 桌面客户端：安装、workspace、标签页、设置。

安装

桌面客户端是一款适用于 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 启用自动更新

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，约 76 MB）：便携式，捆绑了所有依赖项（libwebkit2gtk、libgtk、libsoup 等）。无需系统安装即可在任何 Linux 发行版上运行：
```
chmod +x uVersion_x.y.z_amd64.AppImage
./uVersion_x.y.z_amd64.AppImage
```
.deb 软件包（uVersion_x.y.z_amd64.deb，约 5 MB）：适用于 Ubuntu / Debian / 衍生版。apt 会解析系统依赖项：
```
sudo apt install ./uVersion_x.y.z_amd64.deb
```
应用会安装到 /usr/bin/uVersion。

注意：uversion CLI 捆绑在 Linux 软件包内。首次启动时，客户端会将二进制文件复制到 ~/.local/bin/uversion，并通过 ~/.profile 将 ~/.local/bin 添加到你的 PATH（无需任何手动操作）。

首次启动

首次启动时，客户端会显示登录页面。请输入：

服务器地址：你工作室的地址（例如 https://uversion.mygamestudio.com）
用户名和密码

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

Workspace

workspace 是与服务器 repository 关联的本地文件夹。客户端可以同时管理多个 workspace，它们显示在顶部的标签栏中。每个 workspace 都将其元数据存储在本地文件夹根目录下的 .uversion/ 中：

.uversion/config.toml：owner、repo_id、server URL、workspace UUID
.uversion/checkouts_<workspace_id>.json：你在此 workspace 中持有的 locks
.uversion/changelists_<workspace_id>.json：本地 changelists
.uversion/.last_sync：最后一次 synced 的修订版本（用于增量 sync）

Files 标签页

带有状态筛选器（Synced、Modified、Local only、Locked…）和搜索栏的文件树。

以树状视图显示 workspace 文件及其状态。可用筛选器：

Search：按 path 中的子字符串搜索（不区分大小写）
Status filters：Synced、Modified、Local only、Server only、Locked、Deleted

即使在拥有数万个文件的项目中，视图也能保持流畅。

多选 + 操作

选择多个文件（单击 + shift，或勾选复选框）后：

Checkout：获取 locks（idempotent，对已 locked 的文件重新 checkout 为 no-op）
Sync：重新下载所选文件（当本地文件损坏时很有用）
Revert：release 该 lock，恢复服务器版本

Pending 标签页

当前处于 checked-out 状态、由你或其他用户 locked 的文件。分为两个部分：

Your locks：你可以单独 checkin、revert 或 release
Other users' locks：你可以看到谁持有该 lock，以及在 Production 看板中创建 request 卡片（request 徽章）的 Request release 按钮

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

History 标签页

展开的 commit 及其文件列表，以及该 commit 的 Get all 按钮。

repository commits 的分页列表，包含作者、日期、消息和已更改的文件。点击某个 commit 会打开详情：该 commit 的完整文件列表及其修订版本。

每个 commit 上的 Get all 按钮可下载该修订版本下所有文件的本地副本（用于恢复到稳定状态很有用）。

Production

Production 区域（侧边栏中的专用入口）按仓库汇集项目跟踪。它取代了 Workspace 原来的 Activity 和 Requests 标签页：Workspace 现在专注于文件（Files、Pending、History）。

My tasks

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

Board

看板：To Do / In Progress / Review / Done 列，带优先级、标签、指派人、封面的卡片。

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

请求就是看板卡片 原来的 modification requests（例如 Pending 标签页中对他人持有的 lock 的“Request release”）现在是带有 request 徽章的看板卡片。不再有单独的 Requests 标签页。

打开的卡片：描述、指派人、截止日期、评论、asset/commit 链接、封面。

📷 Screenshot · production-request-cards

Review 列中的 request 类型卡片（徽章）。

Activity

统一仪表板：

24 小时 KPI：commits、活跃提交者、活跃 locks
活动日历：数月内按天的 commits（heatmap）
Recent Checkins 和 Most Modified Directories
Commit History：带有按用户和按路径筛选的分页 commits

Watchlist

监视路径（glob 模式），以便在触及它们的 check-in 时收到通知。每个条目会说明所监视的路径和所跟踪的事件。

Games

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

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

本地 Changelists

📷 Screenshot · client-changelists

分配到两个本地 changelists（例如 default 和 review）的 checked-out 文件。

将你的 checked-out files 分组为多个独立的 commits。changelists 是相对于你的 workspace 的本地概念（绝不会发送到服务器）。适用于：

将紧急修复与正在进行的工作分开
并行准备多次提交而不会全部混在一起
为 WIP 保留一个 "default" changelist，为要 checkin 的内容保留一个 "review"

Settings

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

选项	说明
Default server URL	在登录页面预填
Username	在登录页面预填
Theme	System / Light / Dark
Show hidden files	在 Files 标签页中显示以 `.` 开头的文件
Auto-sync interval	禁用 / 5 分钟 / 15 分钟 / 30 分钟：触发自动增量 sync
Parallel uploads	concurrency 上限（1-32，默认 16）
Default repos path	clone 时默认建议的文件夹

Unreal 面板

📷 Screenshot · client-unreal-panel

带有操作按钮的 Unreal 面板：Open Editor、Compile、Package Game 及其配置选择、Publish Build、Stop。

当客户端在 workspace 中检测到 Unreal 项目（存在 .uproject 文件）时，会出现一个专用面板。它直接从客户端驱动引擎：打开编辑器、编译、打包，无需经过 IDE。大多数操作仅涉及 C++ 项目（纯 Blueprint 项目无需编译）。

Engine path

Unreal 版本会从 .uproject 的 EngineAssociation 自动检测（Windows 注册表、LauncherInstalled.dat 或源码构建）。如果检测失败，你可以手动覆盖。以下所有操作都需要此路径。

Open Editor

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

Compile

📷 Screenshot · client-compile-console

实时显示 Unreal Build Tool 编译输出的内嵌控制台。

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

Generate Project Files

重新生成 IDE 项目文件（Visual Studio、Rider）。在添加或删除源文件后，或在 clone 后很有用。位于面板的 “…”（更多操作）菜单中。

Package Game

通过 RunUAT BuildCookRun 打包游戏，并将结果归档到 workspace 根目录的 Packages/{config}/。有三种配置可选：

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

Packages/ 文件夹默认被忽略（.uversionignore）：打包产物不纳入版本管理，而是通过 Publish Build 分发。

Publish Build

将打包好的构建发布为内部 playtest 版本。你的团队可以从客户端的 Games 页面下载（需要 playtester 角色或已授予的构建访问权限）。客户端会扫描 Packages/{config}/，上传文件（在服务器端去重），然后注册清单。

Open project folder

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

Stop

干净地中断所有正在进行的构建：编译和打包。按钮会显示已停止的构建数量（在后台启动的自动编译可能会被计入）。

自动操作

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

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

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