直接配阿里云镜像可解决90%的composer install卡死、超时等问题，关键需严格满足三要素：键名必须为repo.packagist（单数）、type值必须显式写composer、url末尾必须带/，缺一即静默失效；配后须删vendor和composer.lock并重装，且通过composer install -vvv验证日志中是否出现mirrors.aliyun.com。
直接配阿里云镜像就能解决 90% 的 composer install 卡死、超时、could not find package 问题——不是你网差，是默认源 packagist.org 在海外，物理延迟+防火墙导致 TLS 握手失败或首字节超 30s，配置错一个字符就等于没配。
composer config -g repo.packagist 命令总不生效？检查三要素
这条命令看似简单，但漏掉任意一项就会静默失败：不报错、不提示、查 composer config -g repo.packagist 输出为空或仍是 https://packagist.org。
-
repo.packagist是唯一合法键名：写成repos.packagist（多 s）、Repo.Packagist（大小写混用）、mirror都无效 -
composer是强制 type 值：不能省略，也不能写成vcs、package或空字符串 - 镜像 URL 必须以
/结尾：例如https://mirrors.aliyun.com/composer/✅，少斜杠会拼出/composerpackages.json导致 404 或 fallback 到官方源
正确执行：composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/。验证：composer config -g repo.packagist 输出应为完整 JSON：{"type": "composer", "url": "https://mirrors.aliyun.com/composer/"}。
为什么配了全局镜像，install 还卡在 “Resolving dependencies”？
镜像只管元数据和 zip 包下载路径，但 composer.lock 文件里存的是旧的 dist URL 和哈希值。Composer 会照着 lock 文件里的地址去拉包，根本不管当前镜像设在哪。
- 必须手动删除
vendor/和composer.lock - 再执行
composer install（不是update），才能重新解析依赖、生成适配镜像的新 lock 文件 - CI/CD 流水线尤其要注意：缓存的
composer.lock会让构建持续走错源，得加rm -rf vendor composer.lock步骤
观察日志是否真走镜像：加 -vvv 参数运行 composer install -vvv，看到 Downloading https://mirrors.aliyun.com/composer/... 才算真正生效。
项目级镜像怎么写才不被忽略？repositories 数组首位 + packagist.org: false
团队协作或 CI 环境下，全局配置靠不住（不同用户、不同系统账户读不到同一份配置），必须把镜像写进项目本身。但 Composer 对 composer.json 的结构极其敏感，错一点就当没写。
-
repositories必须是数组（[]），不能是对象（{}） - 阿里云镜像对象必须放在
repositories数组**第一个位置** - 必须显式禁用官方源：
{"packagist.org": false}是独立对象，要和镜像对象并列，不能嵌套进镜像对象里 - 错误写法示例：
"repositories": {"packagist": {"type": "composer", "url": ""}}—— 这是对象格式，且没禁用官方源，会被完全忽略
正确结构片段：
{
"repositories": [
{
"type": "composer",
"url": "https://mirrors.aliyun.com/composer/"
},
{
"packagist.org": false
}
]
}
PHP 环境没调好，镜像再快也白搭
很多新手以为卡在镜像，其实是 PHP 底层函数被禁用或扩展缺失，导致 Composer 根本起不来。
- 检查
php.ini中disable_functions是否禁用了proc_open或putenv：这两个函数被禁会导致composer config -g报错或静默失败 - 确认已启用
openssl和zlib扩展：php -m | grep -E 'openssl|zlib'，缺一不可 - Windows 用户常见问题是安装 PHP 时没勾选 “Add to PATH”，或路径含中文/空格；Linux/macOS 若用宝塔，确保终端调用的是宝塔管理的 PHP（如
/www/server/php/82/bin/php），而非系统老版本
最易被忽略的一点：改完 php.ini 后，CLI 模式需重启终端，Web 模式需重启 PHP-FPM 或 Apache/Nginx——否则配置不生效。
