Composer断网安装包的解压与放置规范-composer-PHP中文网

手动放.tar.gz包报ZipArchive::extractTo错误，是因为Composer启用zip扩展后会在校验等阶段强制调用该方法解压tar包；正确做法是使用path repository方式，将解压后的包通过本地路径仓库引入，避免网络和解压逻辑。

composer断网安装包的解压与放置规范

手动放 .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 和依赖解析强依赖标准目录结构。

Academic Composer Upload

辅助学术写作，包括查找资料、生成大纲、引用扩写及润色风格，同时确保引用规范。

下载

必须解压到 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/ 目录无变化、无报错——临时禁用实时防护再试