Composer不支持"type": "url"仓库类型，仅支持"type": "package"（手动声明单个ZIP）和"type": "artifact"（批量扫描ZIP目录），二者均要求ZIP含有效composer.json且URL可直连。
Composer 可以直接从 HTTP URL 下载并安装 ZIP 包，但必须用 package 仓库类型（不是 composer 或 vcs），且 ZIP 必须符合 Composer 包结构（含 composer.json）。直接配 url 类型仓库会失败——那不是 Composer 支持的仓库类型。
为什么 "type": "url" 在 repositories 里不生效
Composer 官方文档中没有 url 类型仓库。常见误解是以为加个 "type": "url" 就能拉 ZIP，实际会报错：Invalid repository type "url"。真正支持远程 ZIP 的方式只有两种：一是用 "type": "package" 手动声明包信息；二是用 "type": "artifact" 扫描本地或远程 ZIP 目录（需配合 artifact 插件或 Composer 2.2+ 原生支持）。
用 package 类型手动声明 ZIP 包
适用于单个、稳定、不常更新的第三方 ZIP（比如某 SDK 发布页提供的 vendor-name/sdk-v1.2.0.zip）。你得自己写清版本、autoload、dist URL 等信息。
-
dist.url必须是可直连的 HTTPS ZIP 下载地址，且服务器要返回Content-Type: application/zip -
dist.type固定填zip，不能写tar或留空 -
version必须和require中写的完全一致（包括分支别名如dev-master） - ZIP 包根目录下必须有有效的
composer.json，否则 autoload 和依赖解析会出错
示例 composer.json 片段：
在 OpenClaw 中管理 GitHub 仓库、Pull Request、Issue 与工作流。适用于审查 PR、管理 Issue、自动化 GitHub Actions、同步仓库等场景。
{
"repositories": [
{
"type": "package",
"package": {
"name": "acme/sdk",
"version": "1.2.0",
"dist": {
"url": "https://example.com/releases/acme-sdk-1.2.0.zip",
"type": "zip"
},
"autoload": {
"psr-4": { "Acme\Sdk\": "src/" }
}
}
}
],
"require": {
"acme/sdk": "^1.2.0"
}
}
用 artifact 类型批量加载 ZIP 目录（推荐用于内网/私有发布）
适合把一堆 ZIP 放在某个 HTTP 目录下（如 https://intranet/artifacts/），让 Composer 自动扫描。要求 Composer ≥ 2.2，且该目录下所有 ZIP 文件名需含版本号（如 mylib-3.1.0.zip）。
- 目录必须可通过 HTTP GET 访问，且响应头含
Content-Type: text/plain（用于列文件）或允许目录浏览 - ZIP 文件名必须匹配
{name}-{version}.zip格式，否则无法识别 - 不校验 ZIP 内部
composer.json是否存在——如果缺失，安装时会报Package ... has no composer.json - 比
package更省维护，但调试困难：出错时只报 “no matching package”，需手动检查 URL 可达性、文件名、响应头
配置示例：
{
"repositories": [
{
"type": "artifact",
"url": "https://intranet/artifacts/"
}
]
}
常见失败原因和验证步骤
90% 的问题出在 ZIP 获取环节，而不是 Composer 配置本身。
- 用
curl -I https://.../xxx.zip检查 HTTP 状态码是否为 200，Content-Type是否为application/zip - 下载 ZIP 到本地，解压确认根目录有
composer.json，且内容语法正确（可用json_decode(file_get_contents(...), null, 512)快速验证） - 如果 ZIP 是重定向链接（如 GitHub Release 的
302），Composer 默认不跟随——换用真实最终 URL，或加"options": {"http": {"follow_location": true}}（仅限 Composer 2.5+） - 私有域名或自签名证书：确保 PHP cURL 扩展信任对应 CA，或临时设
"options": {"ssl": {"verify_peer": false}}（仅测试）
ZIP 包一旦引入，就绕过了 Git 的版本可追溯性，后续升级只能靠手动改 version 和 dist.url。这点容易被忽略，直到线上环境发现 patch 版本没更新。
