artifact仓库本质是支持离线zip安装的类型，需配置"type":"artifact"和绝对路径，自动扫描.zip/.tar内composer.json构建元数据，不依赖文件名，但要求包结构完整且含合法composer.json。
本地 artifact 仓库的本质是 artifact 类型仓库，不是 path 或 package
很多人误以为把 zip 包扔进某个文件夹、再配个 path 仓库就能装，结果报错 Could not find package xxx at version yyy。根本原因：Composer 的 path 仓库只认源码目录（含 composer.json），不支持直接解析 zip；而真正支持离线 zip 安装的，是 artifact 类型仓库。
artifact 仓库会扫描指定目录下所有 .zip 和 .tar 文件，自动提取其中的 composer.json 来构建包元数据。它不要求 zip 解压，也不要求包名与文件名一致——只要 zip 内部有合法的 composer.json 即可。
- 必须使用
"type": "artifact"，不能写成"type": "package"或漏掉type - 路径必须是**绝对路径**（Windows 下如
C:/my-artifacts，Linux/macOS 下如/opt/composer/artifacts），相对路径会被忽略 - 子目录也会被递归扫描，但符号链接（symlink）默认不跟随（除非加
"options": {"follow_symlinks": true}）
配置 composer.json 启用 artifact 仓库
在项目根目录的 composer.json 中添加 repositories 配置段。注意顺序：本地 artifact 应放在 packagist.org 之前，否则 Composer 仍会优先联网查询。
{
"repositories": [
{
"type": "artifact",
"url": "/opt/composer/artifacts"
},
{
"type": "packagist",
"url": "https://packagist.org"
}
],
"require": {
"monolog/monolog": "^2.10"
}
}
如果只是临时测试，也可用命令行一次性指定：composer install --repository-url=/opt/composer/artifacts，但该方式不持久，且无法同时指定多个仓库。
- 多个 artifact 目录需写多个
repository对象，不能用逗号或分号拼接路径 -
url值末尾斜杠可有可无，但路径中不能含通配符（如artifacts/*.zip） - 若 zip 包内
composer.json中的"name"字段缺失或格式非法，该 zip 会被跳过，且无明确错误提示——建议用composer validate检查 zip 内容
打包规范：zip 必须包含完整包结构，不能只放 src/
一个能被 artifact 正确识别的 zip，必须解压后能直接构成一个标准 Composer 包目录。常见错误是只压缩了 src/ 目录，导致解压后找不到 composer.json。
正确结构示例（压缩前）：
myvendor/mypackage/ ├── composer.json ├── src/ │ └── MyClass.php └── README.md
然后对整个 myvendor/mypackage/ 目录打包（不是只选中 src/），生成 myvendor-mypackage-1.2.3.zip，放到 artifact 目录即可。
- 文件名随意，
artifact不依赖文件名匹配版本或包名 - 支持语义化版本号，只要
composer.json里写了"version": "1.2.3"，安装时写"myvendor/mypackage": "^1.2"就能命中 - 如果 zip 内没有
"version"字段，Composer 会尝试从文件名推断（如foo-bar-2.0.0.zip→2.0.0），但不可靠，强烈建议显式声明
离线安装失败的三个高频原因
即使配置了 artifact，composer install 仍可能失败，往往卡在依赖解析阶段。核心问题不在下载，而在元数据是否完备。
- 依赖链中某个包未放入 artifact 目录（比如
monolog/monolog依赖psr/log，但后者没放 zip）——artifact不会自动补全依赖，所有 require 的包都得手动备齐 - zip 内
composer.json缺少"autoload"或"require"字段，导致 Composer 认为这不是有效包 - PHP 版本约束冲突：
artifact中的包声明了"php": "^8.1"，但当前环境是 PHP 7.4，Composer 会静默跳过该包（不报错），最终找不到满足条件的版本
验证是否真离线：运行 composer install -vvv，观察日志中是否出现 Reading /opt/composer/artifacts/xxx.zip；如果看到 Downloading https://...，说明仍在联网，大概率是仓库配置未生效或包未命中。
