vrc-get 如何自动化 VRChat 项目 CI?GitHub Actions 中一键 resolve VPM 依赖
vrc-get 如何自动化 VRChat 项目 CI?GitHub Actions 中一键 resolve VPM 依赖
如果你正在开发 VRChat 的 World 或 Avatar 项目,一定熟悉过这个场景:每次 CI 构建时都要手动安装 VPM 包,或者 CI 中找不到依赖导致构建失败。vrc-get 是一个开源的 VRChat Package Manager 命令行客户端(CLI)和图形界面工具(ALCOM),支持 Windows、Linux 和 macOS。它可以用一条命令 vrc-get resolve 自动解析并安装项目中所有 VPM 依赖,完美适配 GitHub Actions 等 CI/CD 流水线,让 VRChat 项目的依赖管理从手动操作变成全自动。
💡 本文重点介绍如何在 GitHub Actions 中配置 vrc-get,实现 一键 resolve VPM 依赖,省去 CI 中手动安装包的繁琐步骤。
为什么用 vrc-get 做 CI?
传统的 VRChat 项目管理中,VPM 依赖通常有两种管理方式:
| 方式 | 优点 | 缺点 |
|---|---|---|
| Unity 编辑器手动安装 | 可视化操作 | CI 中无法使用,依赖无法锁定 |
| vrc-get 命令行 | 可脚本化、跨平台、支持版本锁定 | 需要初始配置 |
vrc-get 在 CI 中的核心优势:
- 确定性:
resolve命令严格按照vpm-manifest.json中声明的依赖版本安装,保证每次 CI 构建的依赖一致 - 离线能力:支持
--offline模式,可配合缓存复用仓库数据,加速构建 - 仓库列表导入:通过
repo import从文本文件批量导入 VPM 仓库源,一次配置、处处复用 - 跨平台:同一个 workflow 文件可以在 Windows、macOS、Linux runner 上运行
📌 项目根目录下的 repositories.alcomrepositories 文件就是一个现成的仓库列表示例,包含 90+ 个社区 VPM 源,可以用
vrc-get repo import一键导入。
在 GitHub Actions 中安装 vrc-get
vrc-get 官方提供了专用的 GitHub Actions,无需手动下载二进制文件。根据项目 README 的说明,有两种官方 Action:
setup-vrc-get:安装 vrc-get CLI 到 runner 环境中resolve-vpm-packages:直接解析并安装 VPM 依赖(内部封装了vrc-get resolve)
这两个 Action 由 vrc-get 的维护者 anatawa12 开发和维护。
方式一:使用 resolve-vpm-packages Action(推荐)
这是最简单的方式,一个 Action 完成所有工作。在 .github/workflows/ 目录下创建 workflow 文件:
# .github/workflows/ci.yml
name: CI
on:
push:
branches: [main]
pull_request:
jobs:
resolve:
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v4
- name: Resolve VPM Packages
uses: anatawa12/sh-actions/resolve-vpm-packages@master
with:
project-dir: . # Unity 项目根目录
这个 Action 会自动安装 vrc-get、添加 VRChat 官方仓库源、执行
vrc-get resolve,三步合一。
方式二:手动安装 vrc-get 后使用完整 CLI
如果你需要更多控制(如先导入自定义仓库列表),可以分步操作:
jobs:
build:
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v4
- name: Setup vrc-get
uses: anatawa12/sh-actions/setup-vrc-get@master
- name: Import repository list
run: vrc-get repo import repositories.txt --yes
- name: Resolve VPM dependencies
run: vrc-get resolve -p .
两种方式的完整命令参考 vrc-get/README.md 的 "For GitHub Actions" 部分。
配置 VPM 仓库源:从文本文件批量导入
CI 中最大的问题是:VPM 包来自各种社区仓库,你需要先告诉 vrc-get 去哪里找这些包。
仓库列表文件格式
vrc-get 使用一种简单的文本格式来管理仓库列表,详细规范见 docs/repository-list-file-format.md:
- UTF-8 编码,每行一个仓库 URL
#开头的是注释行- 空行自动忽略
- 支持
vcc://vpm/addRepo?url=...格式添加带自定义 HTTP Header 的仓库
一个简单的示例文件 repositories.txt:
# VRChat 官方仓库
https://vpm.vrchat.com
# 社区仓库示例
https://vpm.nadena.dev/vpm.json
https://poiyomi.github.io/vpm/index.json
在 CI 中导入仓库
将 repositories.txt 提交到你的仓库中,然后在 workflow 中使用 vrc-get repo import 导入:
- name: Import repositories
run: vrc-get repo import repositories.txt --yes
--yes 参数跳过交互式确认提示,这是 CI 环境中必须使用的参数,否则命令会等待用户输入而卡住。
仓库列表的导出与共享
vrc-get 还支持将当前环境的所有仓库源导出为文本文件,方便团队共享配置:
# 在本地机器上导出当前仓库列表
vrc-get repo export > repositories.txt
# 提交到仓库,CI 中即可复用
git add repositories.txt && git commit -m "Add VPM repository list"
这种"仓库列表即代码"的方式,让团队成员和 CI 环境使用完全相同的 VPM 源,避免"在我电脑上能跑"的问题。
仓库管理命令速查
vrc-get 的 repo 子命令提供了完整的仓库管理功能(源码见 vrc-get/src/commands.rs):
| 命令 | 说明 | CI 适用 |
|---|---|---|
vrc-get repo list |
列出所有已添加的仓库 | ✅ 调试用 |
vrc-get repo add <url> [NAME] |
添加单个远程仓库 | ✅ |
vrc-get repo import <file> |
从文件批量导入仓库 | ✅ 推荐 |
vrc-get repo export |
导出当前仓库列表到 stdout | ✅ 生成配置文件 |
vrc-get repo remove <id> |
移除指定仓库 | 按需 |
vrc-get repo cleanup |
清理 Repos 目录缓存 | 按需 |
核心命令:vrc-get resolve 一键安装所有依赖
vrc-get resolve 是 CI 场景下最重要的命令。它的作用等同于 npm install 之于 Node.js 项目——根据项目中的依赖声明,自动下载并安装所有缺失的 VPM 包。
resolve 的工作原理
vrc-get 会读取 Unity 项目中的 vpm-manifest.json 文件,该文件声明了项目直接依赖的 VPM 包及版本范围:
{
"dependencies": {
"com.vrchat.avatars": {
"version": "3.x"
}
}
}
resolve 命令会递归解析所有依赖(包括间接依赖),下载缺失的包并安装到 Packages/ 目录中。源码实现在 vrc-get/src/commands.rs。
常用参数
| 参数 | 说明 |
|---|---|
-p / --project |
指定 Unity 项目目录(默认使用当前目录或父目录) |
--offline |
离线模式,仅使用本地缓存,不连接远程仓库 |
--no-update |
不更新本地仓库缓存(使用上次缓存的数据) |
--yes |
跳过确认提示(CI 必加) |
⚠️ 在 CI 环境中,始终添加
-p参数明确指定项目路径,避免 vrc-get 找不到项目根目录。
一个完整的 CI Workflow 示例
以下是一个覆盖 Windows 和 macOS 的完整示例:
name: VRChat CI
on:
push:
branches: [main]
pull_request:
jobs:
resolve-vpm:
strategy:
matrix:
os: [ubuntu-latest, windows-latest, macos-latest]
runs-on: ${{ matrix.os }}
steps:
- name: Checkout
uses: actions/checkout@v4
- name: Setup vrc-get
uses: anatawa12/sh-actions/setup-vrc-get@master
- name: Import repository list
run: vrc-get repo import repositories.txt --yes
- name: Resolve VPM dependencies
run: vrc-get resolve -p .
这样每次推送或 PR 时,CI 都会自动安装所有 VPM 依赖,确保项目可以正常打开和编译。
利用缓存加速 CI 构建
vrc-get 默认会将下载的仓库索引和包文件缓存到本地。在 CI 中,可以利用 GitHub Actions 的文件缓存功能来加速构建。
仓库缓存目录
vrc-get 将环境数据(包括仓库列表配置和包缓存)存储在用户配置目录中。在 GitHub Actions 中,可以通过缓存该目录来避免每次构建都重新下载:
- name: Cache vrc-get environment
uses: actions/cache@v4
with:
path: |
~/.vrc-get
~/.local/share/vrc-get
key: vrc-get-${{ runner.os }}-${{ hashFiles('repositories.txt') }}
restore-keys: |
vrc-get-${{ runner.os }}-
缓存的
key中包含repositories.txt的文件哈希,当仓库列表变化时会自动触发新的缓存。
离线模式
如果你只需要在 CI 中检查依赖是否完整(而非实际安装),可以使用 --offline 参数:
- name: Check dependencies (offline)
run: vrc-get resolve -p . --offline
这会跳过所有网络请求,仅使用已缓存的数据来验证依赖是否完整。
图形界面替代方案:ALCOM
除了命令行,vrc-get 还提供了图形界面版本 ALCOM(ALCOM 是 VRChat Creator Companion 的开源替代 GUI),适合本地开发时使用。
ALCOM 的包管理面板可以直观地查看项目中所有 VPM 依赖、当前版本和最新版本,支持一键升级。虽然 CI 中主要使用 CLI,但本地开发时通过 ALCOM 管理依赖,再配合 repo export 导出仓库列表,就能在 CI 中无缝复用。
关于 ALCOM 的更多使用细节,可参考 vrc-get-gui/README.md。
常见问题与排查
Q:CI 中 vrc-get resolve 卡住不动?
检查是否添加了 --yes 参数。某些操作(如安装带冲突的包)会触发交互式确认,CI 中无人应答就会永远等待。
Q:repo import 报错 "offline mode"?
--offline 模式下无法添加远程仓库。导入仓库源时不要使用 --offline。
Q:如何只更新指定包?
使用 vrc-get upgrade <包名> [版本],而非 resolve。resolve 是安装所有缺失的包,upgrade 是升级已有包。
Q:vpm-manifest.json 和 Packages/manifest.json 有什么区别?
vpm-manifest.json 是 VPM 特有的依赖清单(由 vrc-get/VCC 管理),manifest.json 是 Unity 原生的包清单。vrc-get 的 resolve 命令会同时处理两者。
Q:如何在 CI 中查看过期的依赖?
- name: Check outdated packages
run: vrc-get outdated -p . --json-format 1
--json-format 1 会输出 JSON 格式的过期包信息,方便后续处理。
小结
vrc-get 让 VRChat 项目的 VPM 依赖管理从"每次手动点几下"变成了 CI 流水线中一行 vrc-get resolve。核心要点回顾:
- 安装:使用
setup-vrc-getAction 或预置二进制 - 配置仓库源:将
repositories.txt提交到仓库,CI 中vrc-get repo import一键导入 - 一键 resolve:
vrc-get resolve -p .自动安装所有 VPM 依赖 - 加速构建:利用 Actions Cache 缓存 vrc-get 环境目录
- 团队协作:
vrc-get repo export导出仓库列表,保证所有人使用相同的 VPM 源
📚 更多命令详情可运行
vrc-get --help查看,完整命令文档见 vrc-get/README.md。仓库列表格式规范见 docs/repository-list-file-format.md。

