换镜像源可解决Composer超时问题，但必须三步到位：确认PHPStorm调用的Composer路径、执行composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/（注意无s、含type、URL末尾带/）、运行composer clear-cache并用composer config -g repo.packagist验证输出非空且为镜像地址。
超时不是 Composer 慢，是它还在直连 packagist.org —— 换镜像源就能解决，但必须配对、验证、清缓存三步到位，缺一不可。
PHPStorm 调用的到底是不是你配的 Composer？
PHPStorm 不自带 Composer，它只是调用你指定的可执行文件。很多人改了全局配置，但 PHPStorm 实际用的是另一个路径下的 composer：
- 打开 Settings / Preferences → PHP → Composer，检查
Path to composer.phar - 如果填的是
composer（无后缀），就去终端运行which composer，输出路径必须和 PHPStorm 里实际调用的一致 - 宝塔用户常见坑：系统级
/usr/local/bin/composer和宝塔内置的/www/server/php/82/bin/composer是两个独立实例，PHPStorm 可能指向没配镜像的那个 - 确认方式：在项目根目录终端执行
composer --version && composer config -g repo.packagist，再对比 PHPStorm 执行时是否报同样错误
repo.packagist 少一个字母就静默失效
90% 的“配了还是慢”源于字段名写错——repos.packagist（多 s）完全无效，Composer 会自动 fallback 到官方源，且不报错：
- 正确命令（全局）：
composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/ - 注意三个硬性要求：字段名是
repo.packagist（无 s）、第二个参数必须是composer（类型声明）、URL 末尾必须有/ - 验证是否生效：
composer config -g repo.packagist，输出应为{"type":"composer","url":"https://mirrors.aliyun.com/composer/"}或纯 URL 字符串；若为空、null或https://packagist.org，说明没生效 - Windows 用户注意配置文件路径：
%USERPROFILE%\AppData\Roaming\Composer\config.json；Linux/macOS 是~/.composer/config.json
PHPStorm UI 不显示真实请求地址，必须加 -vvv 看日志
PHPStorm 界面点 “Reload project” 或右键 “Composer → Update” 时，根本看不到它到底连了哪个源。卡住时你以为在下载，其实可能卡在 TLS 握手或 DNS 解析：
立即学习“PHP免费学习笔记（深入）”；
- 进项目根目录，终端手动执行：
composer update -vvv --no-install 2>&1 | grep "Downloading" - 观察输出里是否出现
mirrors.aliyun.com或mirrors.cloud.tencent.com；没出现，说明镜像根本没走 - 如果看到
cURL error 28，说明是底层网络超时，process-timeout完全不生效，此时该查curl -v https://mirrors.aliyun.com/composer/packages.json卡在哪一步 - CI 或宝塔环境更要警惕：它们常以
www用户运行，而composer config -g默认写的是当前登录用户（如root）的配置，需用sudo -u www composer config -g repo.packagist ...单独配置
换源后第一次 composer update 报 hash 不匹配怎么办
已有 composer.lock 的项目，首次切换镜像源后执行 update，大概率报 Invalid package information 或 hash 校验失败：
- 这不是镜像问题，而是旧 lock 文件记录的是官方源的包元数据，新镜像返回的响应结构或签名略有差异
- 最稳妥做法：删掉
vendor和composer.lock，再跑composer install - 若必须保留 lock 文件，可临时用
--ignore-platform-reqs绕过部分校验，但不推荐用于生产环境 - 别碰 Laravel China 镜像（
https://packagist.laravel-china.org）——自 2025 年底起已频繁返回 502/503，阿里云和腾讯云镜像是目前最稳选择
真正卡住的地方，往往不是“要不要换源”，而是“换没换对”“用没用上”“缓存清没清”。验证永远比猜测快。
