Artifact仓库是Composer在离线或内网中加载本地ZIP包的唯一合规方式，直接扫描指定目录下含合法composer.json的ZIP文件，按name和version匹配安装，不依赖Packagist。
什么是Artifact仓库，为什么不用packagist.org
Composer的artifact仓库是离线或内网场景下加载本地ZIP包的唯一合规方式。它不走网络请求，不依赖Packagist，而是直接扫描指定目录下的.zip文件，按composer.json中定义的name和version匹配安装。如果你在CI/CD中预下载依赖、或公司内网禁止外连、或需要锁定某次构建的二进制快照，artifact比path仓库更可靠——path只支持源码目录，不能加载ZIP。
配置artifact仓库的3个硬性条件
缺一不可，否则composer install会静默跳过或报Could not find package xxx：
-
repositories必须是数组，且类型为artifact，url指向**包含ZIP文件的父目录路径**（不是ZIP本身），结尾不加/ - 每个ZIP包内部**顶层必须有且仅有一个
composer.json**，且其中name和version字段完整、合法（如"name": "myorg/utils","version": "1.2.3"） - ZIP文件名**无关紧要**，但不能有空格或特殊字符（部分系统会解包失败）；推荐用
name-version.zip格式便于排查
示例composer.json片段：
{
"repositories": [
{
"type": "artifact",
"url": "./artifacts"
}
],
"require": {
"myorg/utils": "^1.2.3"
}
}
ZIP包怎么打包才被artifact识别
关键不是压缩工具，而是目录结构。运行zip -r myorg-utils-1.2.3.zip src/ composer.json前，确保：
-
composer.json在ZIP根目录下（解压后直接能看到） - 不要把整个Git仓库塞进去（比如含
.git/或vendor/） - 如果依赖其他包，
composer.json里require字段照写，Composer会在后续解析时自动拉取，artifact只管当前包 - PHP版本约束（
php或ext-xxx）仍生效，不因离线而跳过校验
验证方法：手动解压ZIP，执行php -l composer.json确认语法正确，再检查name/version是否与require一致。
常见失败现象和定位步骤
运行composer install -vvv时注意三处输出：
- 看到
Reading /path/to/artifacts/*.zip→ 说明路径扫描成功；没这句=目录路径错或为空 - 看到
Found package myorg/utils (1.2.3)→ 匹配成功；没这句=ZIP内composer.json的name或version不匹配 - 卡在
Loading composer repositories with package information后无反应 → 检查ZIP是否损坏（unzip -t xxx.zip）或权限问题（Linux下stat ./artifacts看是否可读）
特别注意：artifact仓库**不支持版本别名**（如dev-master as 1.0.x-dev），也**不支持dist.type: "zip"覆盖**——那是package仓库的事。
