如何一次性批量导入VPM仓库?vrc-get完整解析.alcomrepositories格式与vcc自定义协议
如何一次性批量导入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
命令行用户只需要三步:
- 准备一个列表文件(如 repositories.alcomrepositories)
- 执行导入命令:
vrc-get repo import repositories.alcomrepositories
- 在交互提示中确认(输入
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 的导入流程比想象的更严谨——它不只是「点导入就完事」,而是导入前先替你验证每个仓库是否真的可用:
- 选择列表文件:点击仓库页的导入按钮,或直接双击
.alcomrepositories文件打开(系统文件关联在 main.rs 中处理) - 确认仓库列表:弹窗列出将导入的仓库,以及「无法解析、将被忽略」的行
- 并发下载验证:进度条实时显示
downloaded/total,每个仓库逐个拉取,失败的会明确标出原因(重复 ID / 下载失败) - 确认并添加:展开每个仓库可看到它包含的包列表,只把下载成功的仓库写入设置
前端流程代码在 -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。
常见问题速答
❓ 列表里有一行写错了怎么办? 不用慌。无效行会被单独列出并跳过,导入本身照常进行。
❓ 重复导入会报错吗?
不会。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:// 自定义协议则让它同时成为了浏览器深度链接的载体——格式即协议,协议即格式,这正是这个开源小工具值得称道的设计。

