如何一次性批量导入VPM仓库?vrc-get完整解析.alcomrepositories格式与vcc自定义协议

原创2026-11-12 19:05:161,994 阅读

如何一次性批量导入VPM仓库?vrc-get完整解析.alcomrepositories格式与vcc自定义协议

vrc-get 是一款开源、快速的 VRChat Package Manager(VPM)命令行客户端,配套的图形界面 ALCOM 支持通过一个 .alcomrepositories 列表文件批量导入 VPM 仓库,无需在官方 VCC 中逐个添加。本文面向新手,带你看懂列表文件格式的每一条规则、vcc:// 自定义协议的奥秘,并附上命令行与图形界面两种完整操作路径。

为什么要用「批量导入」

如果你用过官方 VRChat Creator Companion(VCC),一定体验过这种痛苦:想加 10 个社区仓库,就得复制粘贴 10 次 URL。vrc-get 用两个设计解决了这个问题:

  • 📄 列表文件:一个文本文件里写满仓库地址,一条命令全部导入
  • 🔗 vcc 自定义协议:用 vcc:// 链接表达「带自定义请求头的仓库」,浏览器点一下就能唤起 ALCOM

项目根目录就提供了一个真实示例文件 repositories.alcomrepositories,里面整理了 90 多个来自社区的 VPM 仓库地址,开头注释明确说明:This can be imported with vrc-get repo import command or Import button on ALCOM(可用 vrc-get repo import 命令或 ALCOM 的导入按钮导入)。

一键批量导入:vrc-get repo import

命令行用户只需要三步:

  1. 准备一个列表文件(如 repositories.alcomrepositories)
  2. 执行导入命令:
vrc-get repo import repositories.alcomrepositories
  1. 在交互提示中确认(输入 y);加 --yes 可跳过确认

命令执行时会先完整预览:列出所有将被导入的仓库(带自定义头的会标注 with headers),并单独列出「无法解析、将被忽略」的行——所以个别坏行不会导致整个导入失败。已经添加过的仓库会被自动跳过(提示 already added so skipping),重复执行命令是安全的。

💡 提示:加 --offline 参数可跳过网络请求、仅使用本地缓存,适合断网环境。

该命令的完整实现位于 RepoImport。

.alcomrepositories 文件格式详解

文件格式非常朴素,但细节决定成败。官方格式文档见 repository-list-file-format.md,规则归纳为 8 条:

# 规则 说明
1 UTF-8 编码 纯文本文件
2 # 之后为注释 每行都支持
3 每行一个仓库 URL 空行被忽略
4 行首尾空白自动去除 只有空格的行被忽略
5 必须是合法 URL 否则记为无效行
6 协议仅支持 http / https / vcc 其他协议直接忽略
7 http(s) 行 = 普通仓库地址 无请求头
8 vcc 行 = 带请求头的仓库 详见下节

一个最小示例长这样:

# This is a comment
https://vpm.anatawa12.com/vpm.json
vcc://vpm/addRepo?url=https://vpm.ureishi.net/repos.json&headers[]=Authorization:Bearer%20token

解析逻辑全部集中在 repositories_file.rs:RepositoriesFile::parse() 返回两组结果——成功解析的仓库列表和无法解析的行,命令行预览和 GUI 对话框展示的就是这两份数据。

vcc 自定义协议揭秘:请求头与深度链接

vcc:// 并不是某个网站的地址,而是一个自定义 URI 协议,专门用来表达「VCC 添加仓库链接」。格式要求非常严格,四条缺一不可:

  • 协议必须是 vcc
  • 主机部分必须是 vpm
  • 路径必须是 /addRepo
  • 查询参数必须包含 url(目标仓库地址,必须是 http/https)

可选的 headers[] 参数用来追加 HTTP 请求头——这对需要 Authorization 等鉴权头的私有仓库非常关键。值按第一个 : 拆分为「头名:头值」,可写多次追加多个头:

vcc://vpm/addRepo?url=https://example.com/repo&headers[]=header-name:header-value

这套解析规则实现在 parse_add_repo_link。

更妙的是它的第二种用法——深度链接(Deep Link)。在 Windows 上,ALCOM 可以把自己注册为 vcc:// 协议的处理器(项目提供了 install-vcc-protocol.bat 一键安装;Linux 的 AppImage 通过写入 .desktop 文件注册)。注册后,浏览器里点一条 vcc://vpm/addRepo?url=... 链接,系统会直接唤起 ALCOM 弹出「添加仓库」确认框。多个文件/链接批量处理时,ALCOM 会合并解析结果再统一确认,相关逻辑见 deep_link_support.rs 与命令行入口 process_args。

ALCOM 图形界面:四步走完成批量导入

不爱敲命令?ALCOM 的导入流程比想象的更严谨——它不只是「点导入就完事」,而是导入前先替你验证每个仓库是否真的可用:

vrc-get 的 ALCOM 图形客户端 VPM 仓库与包管理界面

  1. 选择列表文件:点击仓库页的导入按钮,或直接双击 .alcomrepositories 文件打开(系统文件关联在 main.rs 中处理)
  2. 确认仓库列表:弹窗列出将导入的仓库,以及「无法解析、将被忽略」的行
  3. 并发下载验证:进度条实时显示 downloaded/total,每个仓库逐个拉取,失败的会明确标出原因(重复 ID / 下载失败)
  4. 确认并添加:展开每个仓库可看到它包含的包列表,只把下载成功的仓库写入设置

前端流程代码在 -use-import-repositories.tsx,后端并发下载命令见 environment_import_download_repositories。第 3 步的「重复 ID 检测」尤其贴心:同一仓库换了个 URL 但 ID 相同时,会标为 Duplicated 避免重复添加。

备份与分享:导出你自己的仓库列表

批量导入的反向操作同样简单——把你当前所有远程仓库导出成列表文件,用于备份或多机同步:

vrc-get repo export

ALCOM 中也提供导出功能,默认文件名就是 repositories.alcomrepositories(见 environment_export_repositories)。导出的内容完全遵循上文格式:普通仓库输出纯 URL,带请求头的仓库自动转写成 vcc://vpm/addRepo 形式——这保证了「导出 → 换台电脑导入」的往返一致性,生成逻辑见 export_repositories。

ALCOM 项目列表界面,展示 vrc-get 图形客户端的项目管理功能

常见问题速答

❓ 列表里有一行写错了怎么办? 不用慌。无效行会被单独列出并跳过,导入本身照常进行。

❓ 重复导入会报错吗? 不会。CLI 对已存在的仓库提示 already added so skipping;GUI 则在下载阶段直接标记 Duplicated 并排除。

❓ 能导入本地(文件夹)仓库吗? 列表文件仅支持远程仓库 URL;本地仓库请用 vrc-get repo add <路径> 单独添加。

❓ 项目源码在哪里看? 核心解析库在 vrc-get-vpm/,CLI 在 vrc-get/,图形客户端在 vrc-get-gui/。如需从源码构建,可克隆仓库:git clone https://gitcode.com/gh_mirrors/vrcg/vrc-get

小结

vrc-get 的批量导入体验可以浓缩为一句话:一个纯文本列表 + 一条命令(或一次点击)。.alcomrepositories 文件用极简的规则承载了完整的仓库配置,而 vcc:// 自定义协议则让它同时成为了浏览器深度链接的载体——格式即协议,协议即格式,这正是这个开源小工具值得称道的设计。

登录后查看全文
vrc-get