如何通过Composer配置artifact实现离线安装包的实用方法？

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

Artifact不是下载后手动解压，而是让Composer将本地的ZIP/TAR文件当作标准包源来使用。它不依赖网络、不查询packagist.org、也不走Git克隆，只按文件名匹配版本号——只需压缩包命名规范、路径正确，执行composer install即可直接解压安装。

适用场景：你有一批已打包好的第三方 SDK、内部组件或定制版包（比如 vendor-name/package-name-1.2.0.zip），不想暴露源码，也不愿搭 Satis 镜像。

常见错误现象：Could not find package vendor/name in a version installable using your PHP version，其实是 ZIP 文件名没对上 lock 文件里记录的 dist.shasum 或 version，或者目录结构没按 artifact 要求组织。

• ZIP 文件必须放在 ./packages/archives/ 这类指定路径下（不能嵌套子目录）
• 文件名格式必须为 vendor-name-package-name-version.zip（注意是短横线，不是斜杠）
• composer.json 中 require 的版本号必须和 ZIP 名字里的 version 完全一致（如 "1.2.0" 不能写成 "^1.2"）
• 包内必须包含合法的 composer.json，且 name 字段要与 require 的完全匹配（大小写敏感）

配置 artifact 仓库的最小可行步骤

不用改全局配置，项目级生效即可。重点是路径、命名、锁文件三者咬合。

假设你把所有 ZIP 放在项目根目录下的 ./packages/archives，操作如下：

• 在 composer.json 顶部加 "repositories" 块：

  {"repositories": [{"type": "artifact", "url": "./packages/archives"}]}

• 确保 composer.lock 已存在，且其中每个包的 dist.url 是 https://... 开头的——别动它，artifact 机制会在 install 阶段自动覆盖这个 URL
• 运行 COMPOSER_DISABLE_NETWORK=1 composer install --no-plugins --no-scripts，它会跳过远程校验，直奔 ./packages/archives 找 ZIP
• 如果报错找不到包，用 ls ./packages/archives 确认 ZIP 名是否为 monolog-monolog-3.5.0.zip（不是 monolog/monolog-3.5.0.zip）

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

二者都离线，但行为逻辑完全不同。选错会导致 autoload 失败或版本冲突。

• path 类型：适合你手头有包的完整源码（含 src/、tests/、composer.json），Composer 会软链或复制整个目录，支持 dev-main 这类分支名，但不校验 dist.shasum
• artifact 类型：只认 ZIP 文件，解压后内容必须和线上发布包一致，强制校验 dist.shasum，适合交付物归档、CI 构建产物复用
• 混用风险：如果同一个包同时出现在 path 和 artifact 仓库中，Composer 优先走 path，但 lock 文件若来自 artifact 构建，就会因路径不一致导致 vendor/composer/installed.json 记录错误
• 私有包建议：用 path 做开发，用 artifact 做发布；离线部署时只保留 artifact 配置，删掉 path 块防止干扰

离线执行时最容易被忽略的校验点

即使 ZIP 放对了、配置写对了，composer install 仍可能静默跳过某个包——不是失败，而是“假装装了”，结果运行时报 Class not found。

• 检查 composer.lock 中该包的 dist.type 是否为 zip（artifact 只处理 zip 和 tar，不支持 dist.type: "source"）
• 确认 ZIP 内的 composer.json 里 autoload 字段路径有效（比如 "psr-4": {"Monolog\": "src/"}，而 ZIP 解压后确实有 src/Logger.php）
• PHP 版本必须 ≥ 包的 require.php 声明（artifact 不绕过平台约束，COMPOSER_DISABLE_NETWORK=1 也拦不住这个校验）
• 运行前删掉 vendor/ 和 vendor/composer/installed.json，避免旧缓存污染——artifact 机制只在 clean vendor 下才可靠触发