详解 composer 的 pre-file-download 事件有什么用？-composer-PHP中文网

详解 composer 的 pre-file-download 事件有什么用？

冰火之心

发布： 2025-11-22 12:49:10

原创

916人浏览过

pre-file-download事件用于在Composer下载远程文件前拦截并修改请求，主要实现下载源替换、认证信息注入、请求头修改、日志监控及缓存策略控制。1. 可将官方源替换为国内镜像或私有代理地址以加速下载；2. 支持为私有仓库自动添加Bearer Token、Basic Auth或自定义User-Agent；3. 能记录每次下载的URL、包名和时间戳，便于性能分析与故障排查；4. 结合本地缓存机制可实现离线模式或网络访问控制。该事件不干预依赖解析，专注文件获取环节，是开发性能优化、安全增强类插件的关键钩子。

详解 composer 的 pre-file-download 事件有什么用？

composer 的 pre-file-download 事件在文件实际下载前触发，主要用于对远程资源请求进行拦截或修改。这个事件的核心作用是让你在 Composer 下载任何远程文件（比如包的 zip 压缩包、dist 文件、VCS 克隆地址等）之前，有机会介入并控制下载行为。

1. 控制下载源和镜像替换

通过监听 pre-file-download，你可以动态修改下载的 URL。这在以下场景非常有用：

将官方包仓库（如 packagist.org）的下载地址替换为国内镜像（如阿里云、华为云 Composer 镜像），提升下载速度。
企业内网中使用私有代理或缓存服务器，避免重复从外网拉取资源。
开发调试时强制使用本地测试包或模拟响应。

示例：在插件中修改下载地址

use Composer\IO\IOInterface;
use Composer\Plugin\PluginInterface;
use Composer\EventDispatcher\EventSubscriberInterface;
use Composer\Downloader\FileDownloader;

class MirrorPlugin implements PluginInterface, EventSubscriberInterface
{
    public function activate($composer, $io)
    {
        $composer->getDownloadManager()->addDownloader('file', new class extends FileDownloader {
            public function download($package, $outputDir, $fileName = null, $progress = true, $options = [])
            {
                // 在这里可以修改 $package 的 dist url
                $dist = $package->getDistUrl();
                if (strpos($dist, 'https://api.github.com') !== false) {
                    $dist = str_replace('api.github.com', 'github.com', $dist);
                    // 实际项目中可替换为镜像地址
                }
                return parent::download($package, $outputDir, $fileName, $progress, $options);
            }
        });
    }

    public static function getSubscribedEvents()
    {
        return ['pre-file-download' => 'onPreFileDownload'];
    }

    public function onPreFileDownload($event)
    {
        $protocol = $event->getRemoteFilesystem()->getOptions();
        $url = $event->getProcessedUrl();

        // 可以在这里记录日志、替换域名、添加 header 等
        if (strpos($url, 'packages.json') !== false) {
            // 比如给请求头加自定义标识
            $protocol['http'] = ['header' => "User-Agent: MyComposerClient/1.0"];
        }

        $event->getRemoteFilesystem()->setOptions($protocol);
    }
}

登录后复制