深度解析vrc-get架构:vrc-get-vpm核心库如何统一管理包、仓库与Unity项目
深度解析vrc-get架构:vrc-get-vpm核心库如何统一管理包、仓库与Unity项目
vrc-get 是一个跨平台的 VRChat 包管理器(VPM)开源客户端,提供命令行工具 vrc-get 和图形界面 ALCOM 两种形态。二者背后是同一个 Rust 核心库 vrc-get-vpm,它统一管理仓库(Repository)、包(Package)与 Unity 项目三大对象。本文将带你拆解这套架构的设计思路,帮助你快速理解 vrc-get 是如何做到"一份核心、两个前端"的。
1. 一个仓库,两个面孔:CLI 与 GUI 共享同一核心
vrc-get 仓库(workspace)由几个成员组成,见 Cargo.toml:
| 模块 | 角色 |
|---|---|
vrc-get |
命令行客户端,命令入口在 vrc-get/src/commands.rs |
vrc-get-gui |
图形界面 ALCOM(基于 Tauri),管理界面、日志、仓库导入 |
vrc-get-vpm |
核心库,实现所有 VPM 协议逻辑 |
xtask |
构建、打包与签名工具 |
CLI 的 vrc-get install、vrc-get search、vrc-get repo add 等命令(清单见 README.md)都只是薄薄一层封装,真正的下载、校验、依赖解析全部委托给 vrc-get-vpm。GUI 版本 ALCOM 通过 vrc-get-gui/src/commands/ 以相同方式调用该库,因此两种形态的行为完全一致。
💡 这种"共享核心库"的架构是 vrc-get 最值得关注的设计:新功能只实现一次,CLI 和 GUI 同时受益。
2. vrc-get-vpm 核心库模块全景
核心库入口为 vrc-get-vpm/src/lib.rs,按职责划分为六大模块:
repository/:仓库模型。RemoteRepository(repository/remote.rs)解析远端 JSON;LocalCachedRepository(repository/local.rs)是其本地缓存封装。environment/:用户环境层。包含Settings(设置)、RepoHolder(仓库持有器)、PackageCollection(包集合)、PackageInstaller(包安装器),以及可选的实验性项目管理(LiteDB/SQLite)。unity_project/:Unity 项目操作。UnityProject负责读取项目状态,add_package、resolve、migrate_vpm等子模块对应各个复杂操作。package_manifest/:PackageManifest即包清单(package.json)的类型化表示。version/:版本号、版本范围与 Unity 版本的解析和比较。io/+traits/:异步 IO 抽象与可替换的 HTTP 客户端接口(io/tokio.rs)。
3. 仓库管理:从远端 JSON 到内存视图的三级流水线
vrc-get 对仓库的管理遵循一条清晰的流水线,每一级只负责一件事:
① 远端层 —— RemoteRepository
仓库本质是一个 JSON 文件(含 id、name、packages 字段)。RemoteRepository::download_with_etag(remote.rs)下载它,并支持 ETag 协商——服务器返回"无变化"时直接复用缓存,省去带宽。
② 本地缓存层 —— LocalCachedRepository
下载结果连同自定义 HTTP 请求头、ETag 一起写入 Repos/*.json 缓存文件(见 environment.rs 中的路径常量),实现离线可用。
③ 内存层 —— RepoHolder → PackageCollection
RepoHolder::load(repo_holder.rs)并行加载内置的官方/Curated 仓库与用户添加的仓库;PackageCollection(package_collection.rs)再把所有仓库和用户本地包聚合成一个统一的不可变视图,供 search、install 等命令查询。
用户添加的仓库 URL 还可通过列表文件批量导入,其格式(含带自定义请求头的 vcc://vpm/addRepo 写法)定义在 docs/repository-list-file-format.md,官方示例见 repositories.alcomrepositories。
4. 包管理:统一视图与带校验的安装流水线
无论包来自哪个仓库,还是用户手工放入的本地包,PackageInfo(lib.rs)都把它们统一成同一类型,仅以 Remote/Local 区分来源。这样上层命令完全不需要关心"这个包在哪"。
安装时由 PackageInstaller::install_package(package_installer.rs)执行一条严格流水线:
- 查缓存:先在
Repos/<包名>/下找已下载的 zip; - 下载:缓存未命中才走网络,并合并仓库级与包级 HTTP 请求头;
- SHA-256 校验:与清单中声明的
zipSha256比对,不一致立即删缓存并报错(package_installer.rs); - 解压:失败时回滚目标目录,保证项目不被破坏。
整个流程还通过 AbortCheck(traits.rs)支持中途取消,长时间下载不会卡死进程。
5. Unity 项目管理:以 vpm-manifest.json 为锚点
打开一个项目时,UnityProject::load(unity_project.rs)会同时读取三份状态并交叉核对:
Packages/vpm-manifest.json:vrc-get 的"锁文件",记录已锁定版本与 zip 哈希;Packages/manifest.json:Unity UPM 原生清单;Packages/目录的实际内容:识别出"已安装但未锁定"的包(unlocked_packages)。
这种三方对账让 vrc-get 能准确回答"项目实际装了什么",并为 vrc-get resolve(重新安装全部依赖)和从旧版 VCC/vpm 命令迁移(migrate_vpm.rs)提供可靠基础。添加包则由 AddPackageOperation(add_package.rs)完成:依赖解析 → 下载校验 → 更新清单 → 迁移 Legacy 资产,全部落在同一套抽象之上。
此外,核心库还内置了 Unity 版本兼容规则(如 lib.rs 中的 unity_compatible),防止把面向 Unity 2019 的旧版 VRCSDK 装进 2022 项目这类典型事故。
6. 跨平台的地基:IO 与网络抽象
vrc-get-vpm 刻意不直接依赖具体网络库和文件系统细节:
HttpClienttrait(traits.rs):下载仓库和包都通过该接口进行,测试可注入内存实现;DefaultEnvironmentIo/DefaultProjectIo(io/tokio.rs):把"环境目录"与"项目目录"分成两套 IO 作用域,所有文件操作都经过它,天然支持原子写入与取消;- feature 开关:Unity Hub 集成、项目管理等能力通过 Cargo.toml 的 feature 按需启用,保持核心精简。
正是这些抽象,让 vrc-get 能同时在 Windows、Linux、macOS 上以近乎静态的二进制分发,也让 vrc-get-vpm 可以独立演进而不牵动上层。
7. 总结:三个对象,一套模型
| 对象 | 核心类型 | 关键设计 |
|---|---|---|
| 仓库 | RemoteRepository / LocalCachedRepository / RepoHolder |
ETag 增量更新 + 本地缓存 + 并行加载 |
| 包 | PackageManifest / PackageInfo / PackageInstaller |
远端/本地统一视图,SHA-256 校验 + 缓存 |
| Unity 项目 | UnityProject + vpm-manifest.json |
清单与目录三方对账 |
vrc-get 架构的精髓在于:把"仓库、包、项目"抽象为三层清晰的对象模型,用 vrc-get-vpm 核心库统一承载,CLI 与 GUI 只做呈现。理解了 vrc-get-vpm/src/ 下的 repository、environment、unity_project 三大模块,就掌握了 vrc-get 的心脏。

