Composer 安装 zip 包时 require 不生效？检查 composer.json 的 repositories 配置
Composer 默认不从本地 zip 文件安装包，必须显式声明自定义仓库。直接 composer require vendor/name 会报错 Could not find package vendor/name，因为默认只查 Packagist。
实操建议：
- 在项目根目录的
composer.json中添加repositories块，类型设为package，不是artifact（后者只支持整个目录，不支持单个 zip） -
package方式需手动写明包名、版本、dist 下载地址（支持file://协议或相对路径） - zip 文件必须包含有效的
composer.json（至少含name和version），否则安装失败
示例片段：
{
"repositories": [
{
"type": "package",
"package": {
"name": "myorg/utils",
"version": "1.2.0",
"dist": {
"url": "file://./packages/utils-1.2.0.zip",
"type": "zip"
}
}
}
],
"require": {
"myorg/utils": "^1.2.0"
}
}
离线环境用 composer install 加载已下载的 zip？靠 artifact 仓库 + composer.lock
离线安装的核心是提前把所有依赖打包成 zip，并用 artifact 类型仓库指向它们所在目录。它不校验包内容，只按文件名匹配版本 —— 所以命名必须严格遵循 {vendor}-{name}-{version}.zip 格式。
常见错误现象：
- 运行
composer install报错No zip archive found for myorg/utils at version 1.2.0：zip 文件名不匹配，或路径没加进repositories - 提示
Package operations: 0 installs, 0 updates, 0 removals：composer.lock里记录的是 Packagist 的 dist URL，没被替换成本地路径
实操建议：
- 先在线环境执行
composer install --no-dev，再用composer archive或手动打包vendor/下每个包（推荐用composer archive生成标准命名） -
repositories设为artifact，值为 zip 所在目录绝对路径或相对路径（如"./artifacts"） - 确保离线机器上已有
composer.lock，且该 lock 文件由同一份composer.json+ artifact 配置生成（不能混用在线和离线配置生成的 lock）
artifact vs package：选哪个取决于你有没有源码控制权
如果你能改目标包的 composer.json，用 package 更灵活：可指定任意版本号、支持分支别名、能覆盖 autoload；如果只是拿别人发布的 zip（比如内部 Nexus 私服导出的归档），artifact 是唯一选择 —— 它完全跳过元数据校验，纯靠文件名驱动。
性能与兼容性影响：
-
artifact构建快，但无法做版本约束推导（比如^1.2只能匹配到明确存在的 zip 文件名） -
package支持完整语义化版本解析，但每次composer update都要重新读取 zip 内的composer.json，IO 开销略高 - PHP 7.2+ 和 Composer 2.x 全都支持，不用额外降级
离线安装失败时优先检查这三处
很多问题其实卡在路径或权限这种基础环节，而不是逻辑本身。
-
file://协议在 Windows 上要用三个斜杠（file:///C:/path/to/archive.zip），Linux/macOS 用两个（file:///home/user/archive.zip） - zip 文件必须可读，且解压后顶层目录结构要和
composer.json里写的autoload路径一致（比如"psr-4": {"MyOrg\": "src/"}，那 zip 里就得有src/目录） - 执行
composer install -vvv，看日志里实际尝试访问的 URL 是什么 —— 经常发现配置写对了，但 zip 放错了位置，或者名字多了一个下划线
最麻烦的其实是 zip 包里嵌套了 Git 子模块或 .git 目录，导致解压失败；遇到这种情况，先用 unzip -l xxx.zip 看结构，再手动清理再重压。
