vrc-get 如何自动化 VRChat 项目 CI?GitHub Actions 中一键 resolve VPM 依赖

原创2026-11-12 09:19:462,165 阅读

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 图形界面——VRChat VPM 包管理面板,展示已安装依赖与可升级版本

ALCOM 的包管理面板可以直观地查看项目中所有 VPM 依赖、当前版本和最新版本,支持一键升级。虽然 CI 中主要使用 CLI,但本地开发时通过 ALCOM 管理依赖,再配合 repo export 导出仓库列表,就能在 CI 中无缝复用。

ALCOM 项目列表视图——管理多个 VRChat Unity 项目及其 Unity 版本

关于 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。核心要点回顾:

  1. 安装:使用 setup-vrc-get Action 或预置二进制
  2. 配置仓库源:将 repositories.txt 提交到仓库,CI 中 vrc-get repo import 一键导入
  3. 一键 resolve:vrc-get resolve -p . 自动安装所有 VPM 依赖
  4. 加速构建:利用 Actions Cache 缓存 vrc-get 环境目录
  5. 团队协作:vrc-get repo export 导出仓库列表,保证所有人使用相同的 VPM 源

📚 更多命令详情可运行 vrc-get --help 查看,完整命令文档见 vrc-get/README.md。仓库列表格式规范见 docs/repository-list-file-format.md。

登录后查看全文
vrc-get