根本原因是composer默认process-timeout过低（300秒）且无重试机制，需全局执行composer config -g process-timeout 600并禁用并行下载；github api限流需配置github-oauth.token；ci环境须显式安装php扩展并验证。
Composer报错“Connection timed out”或卡在Downloading，不是网络不通
根本原因不是DNS解析失败或代理没开，而是Composer默认process-timeout太低（默认300秒），且并发下载+无重试机制，在响应慢的源（如国内镜像、私有GitLab）上极易触发超时。常见错误包括curl: (28) Operation timed out或file_get_contents(): failed to open stream: Connection timed out。
- 先临时提高全局超时：运行
composer config -g process-timeout 600（单位秒，600=10分钟） - 禁用并行下载能显著降低连接压力：
composer config -g use-include-path false，再配合环境变量COMPOSER_PROCESS_TIMEOUT=0（部分版本更认这个） - CI/CD中必须显式设置
COMPOSER_PROCESS_TIMEOUT和COMPOSER_HOME，否则容器重启后配置丢失
“API rate limit exceeded”或403错误，本质是GitHub限流，换源无效
这类问题日志里常含https://api.github.com/请求失败，但不会明说“rate limit”，只报403或静默卡住。这不是网络问题，是GitHub对未认证请求的硬性限制：每小时最多60次API调用。镜像源（如阿里云）不转发GitHub API请求，所以换源完全没用。
- 生成Personal Access Token时，只勾选
repo（含public_repo，私有库也够用），read:packages可选，其他权限如delete_repo完全不需要 - 执行命令绑定：
composer config -g github-oauth.github.com <your_token_here></your_token_here>，注意域名是github.com，不是api.github.com - 验证是否生效：
composer config -g github-oauth.github.com应输出掩码后的Token（如ghp_***abc123）；更准的验证方式是curl -H "Authorization: token <your_token_here>" https://api.github.com/rate_limit</your_token_here>，看返回的rate.limit是否为5000
CI环境中composer install失败，90%是因为工作目录和PHP环境没配全
GitHub Actions等CI默认容器里既没切到项目根目录，也没装PHP扩展，composer install一启动就校验ext-zip、ext-xml等，缺一个就直接退出——不是超时，是根本跑不起来。
- 必须用
actions/checkout@v4后加working-directory: ${{ github.workspace }}，或在run前手动cd ${{ github.workspace }} - 别用
sudo apt install composer：Ubuntu官方源版本老旧（常是v2.0.x），且不保证启用必需扩展 - 用
shivammathur/setup-php@v2显式指定php-version和extensions（至少mbstring、xml、zip、curl） - 缓存要分两层：
~/.composer/cache（依赖包缓存）和vendor/（构建产物），key里必须包含composer.lock哈希和PHP版本
卡在“Generating autoload files”不是网络问题，是I/O或递归扫描阻塞
这阶段Composer在递归扫描vendor/下所有文件生成自动加载映射，尤其当存在大量symlink、嵌套过深的包、或挂载在WSL2/Docker for Mac/NTFS卷上时，PHP进程可能被系统限制或I/O阻塞，表现为长时间无响应。
- 运行
composer install -v观察最后几行日志，若停在Generating autoload files之后，基本可确认是此问题 - 临时跳过优化：
composer install --no-autoloader，再手动运行composer dump-autoload --optimize分步排查 - Linux/macOS上检查
ulimit -n是否过低（建议≥4096）；WSL2用户可尝试在/etc/wsl.conf中加fs.inotify.max_user_watches=524288
rate.limit是否真升到5000，以及CI里setup-php漏写了zip扩展导致composer install直接退出——这两处不查日志几乎无法定位。
