手动放.tar.gz包报ZipArchive::extractTo错误，是因为Composer启用zip扩展后会在校验等阶段强制调用该方法解压tar包；正确做法是使用path repository方式，将解压后的包通过本地路径仓库引入，避免网络和解压逻辑。
手动放 .tar.gz 包为什么还报 ZipArchive::extractTo 错误
不是你解压方式不对，而是 Composer 在校验或 fallback 阶段仍会调用 ZipArchive::extractTo() —— 只要 PHP 启用了 zip 扩展（php -m | grep zip 有输出），哪怕你放的是 .tar.gz，它也可能在 checksum 检查、临时提取时强行走 zip 解压路径，而该方法不支持 tar 格式，直接 fatal error。
常见诱因包括：
- PHP 启用了
zip扩展但没装系统tar命令，导致 tar 解压 fallback 失败 - 你把包放进
vendor/但没删composer.lock，composer install仍按 lock 文件尝试远程拉取并解压 - 包的
composer.json中未声明"dist": {"type": "tar"}，Composer 不识别你放的 tar 是合法 dist 包
正确解压后该放哪？路径和结构不能错
手动安装 ≠ 把文件丢进 vendor 就完事。Composer 的 autoload 和依赖解析强依赖标准目录结构。
- 必须解压到
vendor/{vendor-name}/{package-name}/，例如monolog/monolog→vendor/monolog/monolog/ - 解压后的根目录里必须包含完整
composer.json，且含有效autoload字段（如"psr-4": {"Monolog\": "src/"}） -
vendor/autoload.php不会自动感知你手动加的目录；必须运行composer dump-autoload才能注册新包 - 不要运行
composer install或composer 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": "*"
}
}
- 版本号写
"*"或"dev-main"，避免触发远程版本解析 - 运行
composer require my-vendor/my-custom-lib（不是install），Composer 会创建符号链接而非复制文件 - 链接目标是
vendor/my-vendor/my-custom-lib→./packages/my-custom-lib，后续修改源码立即生效
Windows 下特别注意的两个坑
断网安装在 Windows 上失败率更高，多数卡在路径和权限上。
- 路径不能含中文、空格或反斜杠（
）；./packages/my lib会导致生成的 wrapper 脚本第一行解析失败，报bash: ./my: No such file or directory - 若用 Git Bash 或 WSL，确保
php.exe路径在$PATH中，且php -v可执行；否则composer dump-autoload会静默失败 - 防病毒软件（尤其是 Windows Defender）可能拦截
composer.phar对本地目录的写入，表现为vendor/目录无变化、无报错——临时禁用实时防护再试
path repository 是唯一同时满足可复现、可调试、不破坏 autoload 的方案；其他方式都依赖运气和环境状态。 
