pre-file-download事件是Composer在下载远程资源前触发的钩子，可用于修改下载URL、添加认证头或记录日志。通过创建实现PluginInterface的插件类并监听该事件，结合EventHandler处理逻辑，可实现镜像替换、私有仓库认证等功能。常见应用场景包括加速GitHub下载、添加请求头、审计监控等，但需注意目标地址内容一致性及性能影响，避免校验失败或安装延迟。
Composer 的 pre-file-download 事件允许你在 Composer 下载任何远程资源（如包的 zip 文件、dist 文件或源代码）之前执行自定义逻辑。这个事件在需要对下载行为进行拦截、修改或记录时非常有用，比如替换镜像源、添加认证头、调试网络请求等。
什么是 pre-file-download 事件？
该事件是 Composer 提供的一个钩子（Hook），在每次准备通过 HTTP/HTTPS 下载文件前触发。它接收一个 PreFileDownloadEvent 对象，包含当前下载的 URL 和用于发送请求的 IO 和 HTTP 实例。
你可以通过插件或项目级脚本来监听此事件，从而控制下载过程。
如何使用 pre-file-download 事件？
使用该事件通常需要编写一个 Composer 插件，或者在项目的 composer.json 中注册一个脚本类。以下是具体步骤：
首先定义一个类来处理事件：
// ExamplePlugin/EventHandler.php
namespace ExamplePlugin;
use Composer\IO\IOInterface;
use Composer\Plugin\PreFileDownloadEvent;
use Composer\Plugin\PluginInterface;
class EventHandler
{
public static function onPreFileDownload(PreFileDownloadEvent $event)
{
$httpDownloader = $event->getHttpDownloader();
$url = $event->getProcessedUrl();
// 示例：输出正在下载的 URL
$event->getIO()->writeError("即将下载: " . $url);
// 示例：替换为国内镜像（仅示例逻辑）
if (strpos($url, 'github.com') !== false) {
$mirroredUrl = str_replace('github.com', 'ghproxy.com', $url);
$event->setProcessedUrl($mirroredUrl);
$event->getIO()->writeError("已镜像到: " . $mirroredUrl);
}
// 示例：添加自定义请求头（如认证）
// $httpDownloader->addOptions(['headers' => ['Authorization' => 'token xxx']]);
}
}
2. 创建插件主类
创建一个实现 PluginInterface 的类来注册事件：
// ExamplePlugin/Plugin.php
namespace ExamplePlugin;
use Composer\Composer;
use Composer\EventDispatcher\EventSubscriberInterface;
use Composer\IO\IOInterface;
use Composer\Plugin\PluginInterface;
class Plugin implements PluginInterface, EventSubscriberInterface
{
public function activate(Composer $composer, IOInterface $io)
{
// 激活插件
}
public static function getSubscribedEvents()
{
return [
'pre-file-download' => [['onPreFileDownload', 0]]
];
}
}
3. 配置 composer.json
在你的插件目录中配置 composer.json：
{
"name": "example/composer-mirror-plugin",
"type": "composer-plugin",
"autoload": {
"psr-4": { "ExamplePlugin\\": "" }
},
"require": {
"composer-plugin-api": "^2.0"
},
"extra": {
"class": "ExamplePlugin\\Plugin"
}
}
4. 安装并启用插件
将插件安装到全局或项目中：
composer require example/composer-mirror-plugin
安装后，Composer 会自动激活插件，pre-file-download 事件就会被监听。
常见应用场景
- 加速下载：将 GitHub 等国外链接替换为国内镜像代理（如 ghproxy.com、jsdelivr）。
- 私有仓库认证：为特定域名添加 Token 或 Basic Auth 请求头。
- 日志与监控：记录所有下载请求，用于调试或审计。
- 阻止特定下载：根据 URL 规则抛出异常中断下载（谨慎使用）。
注意事项
修改下载 URL 或请求头时需确保目标地址可访问且内容一致，否则会导致包完整性校验失败。同时，避免在事件中执行耗时操作，以免影响整体安装性能。
基本上就这些。pre-file-download 是一个强大但需谨慎使用的机制，适合在企业环境或特殊网络条件下定制 Composer 行为。不复杂但容易忽略细节，比如 URL 替换后的签名或重定向问题。
