GitHub 安装源标准
最后更新 2026年11月1日
「下载管理」除了创意工坊，还可以直接从公开的 GitHub 仓库取回作品。仓库本身就是作品包：客户端读仓库根目录的 package.json，按这份清单校验，再把该提交的源码归档下载下来。作者不需要另外打 release、也不需要上传 zip 资产。
本页是这类仓库需要满足的约定。玩家侧的操作步骤见下载管理，清单字段见星际枢纽压缩包标准。
客户端做的事
点「检查并下载」后，应用按四步取回内容：
- 用「仓库地址」与「分支」向 GitHub 查询该引用的提交号，并固定在这个提交上。
- 读取该提交根目录的
package.json（上限 128 KiB），按星际枢纽标准校验，并要求version是完整的语义化版本。 - 校验通过后显示预览（名称、简介、作者、版本、类型、战役、
SCNID等清单里有的字段），确认后才开始下载。 - 下载该提交的源码归档，落到下载目录，显示为「已完成」；随后由玩家点「安装」进入正常的安装流程。
关键点是提交号固定：预览时就把分支解析成具体提交并记录下来，下载用的还是这个提交，所以检查之后作者再往分支推新提交，也不会影响本次下载取到的内容。想要拿到新版本，重新建一次任务即可。
仓库要满足什么
| 要求 | 说明 |
|---|---|
| 仓库公开 | 不读私有仓库，也不需要登录；接口地址固定为 github.com、api.github.com、raw.githubusercontent.com、codeload.github.com |
根目录有 package.json | 只能是仓库根目录，不能放进子文件夹；一个仓库只能有一个作品 |
| 清单符合标准 | 字段、类型、资源路径按星际枢纽压缩包标准校验 |
| 版本号完整 | 必须是 1.2.3 这类完整语义化版本，1.2、v1.2.3、最新版 都不行 |
| 资源真实存在 | 清单里 maps[]、mods[] 声明的每个 source_path，都必须能在仓库里找到文件或组件目录 |
| 归档结构简单 | GitHub 打出的归档只有一层 <仓库名>-<提交号>/ 目录，作品文件就在这一层里，不能嵌套多层外壳 |
实际含义很直接：仓库根目录就是作品包的根目录。把 Maps/、Mods/、package.json 直接放在仓库根下即可；为了好看再套一层 src/ 或 pack/ 目录会被判为清单不在根部。
仓库里可以放手稿、构建脚本、README.md 这类与安装无关的文件：它们会随归档一起下载，但只有清单声明的资源与附件会被安装。
地址与分支怎么写
「仓库地址」必须是这种形式：
https://github.com/所有者/仓库
- 只接受
https://，不接受http://，也不接受网页里的分支路径（/tree/main）或文件路径。 - 结尾带不带
/都可以；写成.git结尾会自动去掉。 - 所有者只能是字母、数字与
-，且以字母或数字开头；仓库名可用字母、数字与_ . -，但不能是.、..或单独的.git。 - 不支持 GitHub Enterprise 或其他托管平台——地址前缀固定为
github.com。
「分支」可以填分支名、标签或提交号，默认 main：
| 可以写 | 不能写 |
|---|---|
main、release/1.x、v1.2.0、完整的 40 位提交号 | 以 / 开头或结尾、含 .. 或 @{、含空白与 ~ ^ : ? * [ \、含控制字符 |
每一段路径还不能以 . 开头、不能以 . 或 .lock 结尾。填错时窗口会即时提示「请输入 https://github.com/所有者/仓库 格式的地址」或「请输入分支名称」。
体积与结构
GitHub 安装源不设自己的体积门槛：既没有「归档文件最大多少 MB」，也不受创意工坊的创作者额度约束。只要仓库推得上去、归档打得出来，客户端就照单取回；真正限制规模的是 GitHub 对单个文件与仓库体积的规则，那与我们无关，也不在我们的检查范围内。
会被拒绝的只有结构问题。解压前，客户端会把归档的条目过一遍，这些判断与作品大小无关，只用来挡掉无法安全解压的包：
- 路径里出现绝对路径、盘符、
..，或 Windows 保留名（con、aux、com1等）。 - 两个文件只差大小写，解到 Windows 上会互相覆盖。
- 单条路径层级过深，或归档条目数量极多——这类包多半是打包工具出了错。
- 解压后总量远超合理范围（防止压缩炸弹的硬线），正常战役与模组不会触及。
命中时窗口给的是「压缩包结构不安全」一类提示，按正常的目录层级重新打包即可。清单本身的读取上限是独立的一条：根目录 package.json 不能超过 128 KiB，正常清单只有几 KB。
需要控制分发体积时，通常不是为了过检查，而是为了玩家下载体验：把模组拆成独立的依赖包，在 dependencies 里声明，让安装器先装上游。
常见失败与原因
| 现象 | 可能原因 |
|---|---|
提示「无法创建下载任务」，并要求检查仓库是否公开、分支是否存在、根目录 package.json 是否符合标准 | 仓库私有或已删除；分支、标签、提交号写错；根目录没有清单；清单字段不合法；版本号不是完整语义化版本 |
| 预览里缺字段 | 清单能读，但 name、description、author、version 等字段本身没写 |
| 任务失败且提示资源缺失 | 清单声明的 .SC2Map / .SC2Mod 不在仓库里，或大小写、相对路径写错 |
| 提示清单不在根目录 | 作品被放进了子文件夹，或仓库里同时存在多份 package.json |
| 提示清单在检查后发生变化 | 极少数情况下 GitHub 返回的内容与固定提交不一致，重新建一次任务即可 |
与创意工坊的分工
GitHub 安装源是分发通道，不是发布渠道：它不经过审核、没有版本记录，也不产生作品编号。要让作品出现在创意工坊、能被按 SCNID 下载，仍然要在创作者中心创建作品并上传版本。
两者可以并存：仓库持续开发，稳定版本再上传到工坊。仓库里的 scnid 字段填该项目实际分配的编号，客户端不会因为这个字段就把仓库内容当成工坊作品。