composer如何配置本地artifact仓库安装zip包_composer离线安装方法【教程】

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://...，说明仍在联网，大概率是仓库配置未生效或包未命中。