Composer如何安装非Packagist托管的Zip格式包？（本地集成）

composer 用 path 仓库加载本地 ZIP 包需先解压并补全 composer.json（含合法 name 字段），再配置 path 仓库路径，版本必须匹配 version 值或目录名规则；package 类型因维护复杂、不支持 file:// 而不推荐。

用 path 仓库类型加载本地 ZIP 包

Composer 默认不支持直接安装任意 ZIP 文件，必须通过定义 path 类型仓库，并让 ZIP 解压后路径符合 Composer 的包结构（含 composer.json）才能识别。这不是“安装 ZIP”，而是把解压后的本地目录当成本地包源。

• 先解压 ZIP 到一个固定路径，比如 ./packages/my-legacy-lib/
• 确保该目录下有合法的 composer.json，且其中 name 字段格式为 vendor/name（如 "acme/utils"）
• 在项目根目录的 composer.json 中添加仓库配置：

  {   "repositories": [     {       "type": "path",       "url": "./packages/my-legacy-lib"     }   ] }

• 然后运行 composer require acme/utils:dev-main（版本需与 composer.json 中 version 或分支名匹配）

path 仓库的版本写法容易出错

本地 path 包不走 git，所以不能用 dev-master 这类基于远程分支的别名——它依赖的是目录里 composer.json 的 version 值或文件系统中的目录名规则。

• 如果 composer.json 里写了 "version": "1.2.0"，就必须用 1.2.0 作为版本约束
• 如果没写 version，Composer 会 fallback 到目录名：比如目录叫 my-legacy-lib-dev，就只能用 dev-dev；叫 my-legacy-lib-main，就得用 dev-main
• 运行 composer show acme/utils 可确认实际解析出的版本号，避免盲目猜

ZIP 包没 composer.json 怎么办？

直接扔 ZIP 进来是无效的。必须补一个最小可用的 composer.json，否则 Composer 根本不认这是个包。

• 最简内容只需三字段：name、autoload（哪怕空）、type（可选）：

  {   "name": "acme/utils",   "type": "library",   "autoload": {     "psr-4": {}   } }

• 如果原 ZIP 里有 PHP 类文件，建议补上真实 autoload 映射，比如 "src/" 目录对应 "AcmeUtils"
• 别漏掉 name —— 缺失会导致 require 失败并报错 Could not find package acme/utils

为什么不用 package 类型仓库？

package 类型理论上能绕过本地目录，直接描述 ZIP 内容，但实际非常脆弱：它要求你手动声明所有 autoloading、dist URL、checksum，且不支持自动更新，维护成本远高于 path。

• package 仓库里写的 dist.url 必须是 http(S) 地址，本地 file:// 路径多数版本不支持，会报 Failed to download
• 每次 ZIP 内容变更，都得手动改 dist.shasum 和 version，而 path 仓库改完代码直接 composer update 就行
• 除非 ZIP 来自 CI 构建产物且有稳定 HTTP 分发地址，否则优先走 path

真正卡住人的往往不是 ZIP 怎么装，而是解压后忘了补 composer.json，或者补了但 name 格式不对、版本对不上——这些地方没提示，只报“找不到包”。