pre-file-download事件用于在Composer下载远程文件前拦截并修改请求，主要实现下载源替换、认证信息注入、请求头修改、日志监控及缓存策略控制。1. 可将官方源替换为国内镜像或私有代理地址以加速下载；2. 支持为私有仓库自动添加Bearer Token、Basic Auth或自定义User-Agent；3. 能记录每次下载的URL、包名和时间戳，便于性能分析与故障排查；4. 结合本地缓存机制可实现离线模式或网络访问控制。该事件不干预依赖解析，专注文件获取环节，是开发性能优化、安全增强类插件的关键钩子。
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);
}
}
2. 添加认证信息或请求头
某些私有仓库或 CDN 资源需要特定的 token、token 或 header 才能访问。pre-file-download 提供了一个统一入口来注入这些认证信息。
- 自动添加 Bearer Token 到请求头。
- 为特定域名配置用户名密码（HTTP Basic Auth）。
- 设置自定义 User-Agent 便于服务端识别流量来源。
3. 日志与监控
你可以在每个文件下载前记录 URL、目标包名、时间戳等信息，用于：
- 分析依赖下载性能瓶颈。
- 审计哪些外部资源被引用。
- 排查网络问题或失败请求的原因。
4. 实现离线模式或缓存策略
虽然不能直接阻止下载流程（除非抛出异常），但可以通过该事件检查本地是否有缓存副本，或结合其他机制实现预加载、跳过等逻辑。
- 判断某个 URL 是否已存在于本地缓存目录。
- 根据环境变量决定是否允许外网下载。
基本上就这些。pre-file-download 是 Composer 插件开发中非常实用的钩子，尤其适合做透明代理、安全加固、性能优化类的功能。它不改变依赖解析过程，但能精细控制“获取文件”这一关键步骤。
