如何通过Composer artifact功能安装配置离线包？

本文共计1129个文字，预计阅读时间需要5分钟。

`Composer 的 artifact 类型仓库并非把任意 ZIP 文件丢进去就能用，它对目录结构和包命名有硬性要求。不按规范组织，composer install 会静默跳过或报错 `Could not find a matching version`。

• 你指定的 url 必须是一个**纯文件夹路径**（如 ./packages/archives），里面不能有子仓库，只放 ZIP/TAR 包
• 每个包 ZIP 文件名必须严格为 vendor-name-version.zip（例如 monolog/monolog-3.5.0.zip）——注意斜杠是 /，不是 Windows 的 \；版本号必须和 composer.lock 中记录的完全一致（包括 -beta1 这类后缀）
• ZIP 包内必须包含有效的 composer.json（含 name、version、autoload 等字段），且该 composer.json 的 name 必须和 ZIP 文件名中的 vendor-name 完全匹配
• 不支持嵌套子目录，不支持 .tar.gz（仅 .zip 和 .tar，但 .tar 在 Windows 下易出错，建议统一用 .zip）

如何生成符合 artifact 要求的 ZIP 包

别手动打包 —— 手动压缩容易漏 composer.json、写错路径、或用错压缩格式。正确方式是让 Composer 自己导出：

• 在有网机器上，先确保目标包已安装在 vendor/ 中（比如 monolog/monolog）
• 运行：composer archive monolog/monolog --format=zip --dir=./packages/archives
• 执行前确认项目根目录下有 composer.json 且未被修改，否则 archive 可能打包 dev 分支代码而非 lock 文件锁定的正式版
• 如果要打包整个项目所有依赖，需配合 composer-satis 或 toran-proxy 工具生成完整索引，单靠 archive 不递归处理依赖树

配置 artifact 仓库后仍报 “Could not fetch” 的原因

配了 "type": "artifact" 却还联网失败，说明 Composer 仍在尝试回源 —— 它默认开启 packagist.org fallback，哪怕 artifact 目录里缺一个包，也会立刻转向远程请求。

• 必须禁用远程回源：composer config repos.packagist false（注意不是注释掉，而是显式设为 false）
• 环境变量 COMPOSER_DISABLE_NETWORK=1 是兜底手段，但不能替代 repos.packagist false；两者建议同时启用
• 检查 composer.lock 中对应包的 dist.url 字段：离线时它应是类似 file:///full/path/to/packages/archives/monolog-monolog-3.5.0.zip 的本地路径；如果不是，说明 artifact 仓库没被识别，或包名/版本不匹配
• 运行 composer install -v 观察日志：若出现 Loading from cache，说明它绕过了 artifact，正在读 ~/.composer/cache —— 此时需清缓存：composer clear-cache 再试

artifact vs path：什么时候该选哪个

两者都离线可用，但适用场景完全不同，混用反而增加维护成本。

• artifact：适合部署阶段 —— 包已冻结、不再修改、需分发给多台离线机。优点是 vendor 下为真实副本（非链接），无权限/挂载路径问题；缺点是每次加新包都要重新生成 ZIP、更新仓库目录、再跑 install
• path：适合开发调试阶段 —— 你正改一个私有组件，想实时看到效果。优点是改完源码立即生效（因 vendor 下是符号链接）；缺点是 Docker 挂载变更、IDE 重命名父目录后链接失效，且 Windows 下是复制而非链接，体积大、同步慢
• 别在一个项目里同时配两种类型指向同一包；也别用 path 去引用一个本该用 artifact 分发的稳定版本 —— 后者会导致不同机器上 vendor 内容不一致

真正卡住人的从来不是“怎么配”，而是 composer.lock 里那个 dist.url 是否指向本地、以及 repos.packagist 是否被彻底关闭。只要这两点没确认清楚，其他操作都是在掩盖问题。