composer报ziparchive::extractto错误是因为启用zip扩展后，即使手动放.tar.gz也会触发ziparchive解压逻辑；正确做法是用path repository方式映射本地解压包，避免解压流程。
为什么手动下载 .tar.gz 包后 composer install 仍报 ZipArchive::extractTo 错误
这不是包格式本身的问题，而是 Composer 在解压阶段默认信任 ZipArchive 扩展——哪怕你手动放的是 .tar.gz，只要 PHP 启用了 zip 扩展，Composer 就可能在 checksum 校验、临时提取或 fallback 流程中调用 ZipArchive::extractTo()，而该方法无法处理 tar 文件，直接抛出致命错误。
常见诱因包括：
- PHP 已启用
zip扩展（php -m | grep zip可确认），但未安装phar或系统tar命令，导致 tar 解压路径不可用 - 你把
.tar.gz放进vendor/但没删composer.lock，composer install仍按 lock 文件尝试远程拉取并解压 - 包的
composer.json中未声明"dist": {"type": "tar"}，Composer 不识别你放的 tar 是合法 dist 包
怎样让 Composer 正确加载你手动下载的 .zip 包
手动放 zip 包不是“复制粘贴就行”，必须绕过 Composer 的校验与解压逻辑，让它跳过下载阶段，只做路径映射和 autoload 注册。
操作要点：
- 包必须解压到标准路径：
vendor/{vendor-name}/{package-name}/，例如monolog/monolog→vendor/monolog/monolog/ - 解压后目录里必须包含完整的
composer.json（含autoload字段），否则vendor/autoload.php不会注册该包 - 在项目根目录
composer.json的require中声明该包，版本号写成"dev-main"或"*"，避免触发版本解析冲突 - 运行
composer dump-autoload，而不是install或update—— 后两者会清空 vendor 并重拉
用 path repository 强制走本地目录（推荐方案）
这是最干净、可复现、不污染全局 vendor 的方式，适用于测试私有包、离线环境或 CI 中预置依赖。
步骤如下：
- 把解压好的包（含
composer.json）放在任意本地路径，如./packages/my-custom-lib/ - 在项目根目录
composer.json中添加仓库配置：
{
"repositories": [
{
"type": "path",
"url": "./packages/my-custom-lib"
}
],
"require": {
"my-vendor/my-custom-lib": "*"
}
}
-
composer require my-vendor/my-custom-lib:dev-main（注意用dev-main而非具体 tag，path 类型不支持语义化版本约束） - Composer 会创建符号链接（Linux/macOS）或复制（Windows），而非解压归档 —— 彻底避开
ZipArchive和tar的所有坑
手动下载后怎么验证是否生效
别只看 vendor/ 目录有没有文件，关键验证点在自动加载和运行时行为：
- 执行
composer show my-vendor/my-package，输出应包含source类型为path或显示本地路径 - 在代码中
use MyVendor\MyPackage\SomeClass;并实例化，确认不报Class not found - 检查
vendor/composer/autoload_psr4.php，确认该包的命名空间前缀已写入映射数组 - 如果包含 bin 脚本（如
bin/mytool），运行composer bin my-package list看是否识别
真正容易被忽略的是：path repository 模式下，修改本地包代码会实时生效，但 composer update 会破坏符号链接；若需保留链接，应改用 composer install --no-scripts 或禁用自动更新策略。
