如何使用Composer引用本地的ZIP文件作为依赖包？（Artifact Repository）

composer 支持通过 type: “package” 仓库类型引用本地 ZIP 文件，需手动声明包名、版本、dist（含 file:// 绝对路径或相对路径）、autoload 等元信息；ZIP 结构须扁平，避免外层目录；修改 ZIP 后需手动清理 vendor 和 lock 文件并执行 composer update 刷新。

直接在 composer.json 中用 package 仓库类型引用本地 ZIP

Composer 本身不支持像 maven 那样直接配置本地 artifact 仓库，但可以通过自定义 package 类型仓库把本地 ZIP 当作一个“假包”来安装。关键不是让 Composer 去扫描目录，而是显式声明这个 ZIP 对应的包名、版本和源信息。

常见错误是试图在 repositories 里写 "type": "artifact" 并指向一个 ZIP 文件路径——这会报错：Invalid repository type "artifact"，因为 artifact 类型只在私有 Satis/Satis-like 服务中有效，且要求 ZIP 文件名严格匹配 vendor/name-version.zip 格式，本地文件系统无法自动解析。

• 必须使用 "type": "package"
• "dist" 字段需完整指定 "url"（支持 file:// 协议或相对路径）、"type"（固定为 zip）、"reference"（可空，但建议填个哈希或时间戳用于缓存失效）
• "autoload" 和其他元信息必须手动补全，Composer 不会从 ZIP 中读取 composer.json

{   "repositories": [     {       "type": "package",       "package": {         "name": "myorg/my-legacy-lib",         "version": "1.2.3",         "dist": {           "url": "./packages/my-legacy-lib-1.2.3.zip",           "type": "zip",           "reference": "20240520"         },         "autoload": {           "psr-4": {             "MyLegacy\": "src/"           }         }       }     }   ],   "require": {     "myorg/my-legacy-lib": "^1.2.3"   } }

用 file:// URL 引用 ZIP 时路径必须绝对或正确解析

如果 ZIP 不在项目根目录下，用相对路径（如 "./packages/xxx.zip"）通常可行，但某些 Composer 版本或运行环境（如 windows + git bash）可能解析失败，表现为 Could not fetch https://api.github.com/... (404) 或静默跳过下载。

更稳妥的方式是用 file:// 绝对路径，尤其在 CI 或多用户环境中：

• linux/macOS：用 "url": "file:///home/user/project/packages/mylib-1.2.3.zip"
• Windows：用 "url": "file:///C:/project/packages/mylib-1.2.3.zip"（注意三个斜杠，盘符大写）
• 避免空格和中文路径，否则可能触发 curl 错误或 ZIP 解压失败

ZIP 包结构必须符合 Composer 安装预期

Composer 解压 ZIP 后，会把内容当作包的根目录。如果 ZIP 打包时多了一层文件夹（比如压缩了整个 my-legacy-lib-1.2.3/ 目录），那么 autoload 里的 "src/" 就会找不到——实际路径变成 my-legacy-lib-1.2.3/src/。

解决方法只有两个：

• 打包 ZIP 时，选中 src/、composer.json 等文件，**不要包含外层目录**（即解压后直接看到 src/，而不是 my-legacy-lib-1.2.3/src/）
• 或者在 "autoload" 中调整路径，例如写成 "MyLegacy\": "my-legacy-lib-1.2.3/src/"，但这会让版本号硬编码进 autoload，不可维护

验证方式：手动解压 ZIP，确认结构是否扁平。

安装后不会自动更新，且 composer update 可能忽略本地变更

一旦 ZIP 被成功安装，Composer 会把它缓存到 vendor/，后续 composer install 不再读取原始 ZIP。如果你修改了 ZIP 文件内容，必须强制刷新：

• 删掉 vendor/myorg/my-legacy-lib 和 composer.lock 中对应条目
• 运行 composer update myorg/my-legacy-lib --with-dependencies
• 或者加 --no-cache 参数绕过本地缓存（但不推荐用于 CI）

没有钩子能监听 ZIP 文件变动，所以这种模式只适合稳定快照，不适合开发态热更新。

真正需要频繁迭代的本地包，应该用 "path" 仓库类型指向本地 Git 仓库或文件夹，而不是 ZIP。