必须配置国内镜像源才能正常开发，推荐阿里云镜像：composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/，注意项目级repositories配置会覆盖全局设置，且需检查权限与xdebug干扰。
国内直接用 packagist.org 安装 PHP 包，大概率会卡在 Installing dependencies 或报 Connection timed out 错误——这不是你网络差，是源服务器物理距离和路由策略导致的必然结果。必须换镜像，且要一次性配对到位。
为什么 composer config -g repo.packagist 有时不生效
全局配置只影响新项目，已有项目的 composer.json 里如果显式写了 "repositories" 字段，会优先使用它覆盖全局设置；另外 Windows 下若用 PHPStudy 或 XAMPP，可能因权限问题写入失败，导致看似执行成功但实际没改到生效位置。
- 先运行
composer config -g --list确认当前全局配置路径是否可写（输出中home对应目录需有写权限） - 检查项目根目录下是否存在
composer.json，若有，打开看是否有"repositories"块，删掉或注释掉再试 - 阿里云镜像最稳，命令是：
composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/ - 腾讯云备用（部分企业内网拦截阿里云）：
composer config -g repo.packagist composer https://mirrors.cloud.tencent.com/composer/
composer install 还很慢？可能是没关 xdebug
PHP 扩展 xdebug 在 Composer 加载大量类文件时会严重拖慢 autoloader 生成速度，尤其 Laravel、ThinkPHP 这类框架，vendor/autoload.php 初始化阶段可能多耗 3–5 秒。
- 临时禁用：运行
php -d extension= -d zend_extension= composer install - 永久方案：在开发环境的
php.ini中把xdebug相关行前面加;注释掉，保存后重启 Web 服务或 CLI PHP - 验证是否生效：执行
php -m | grep xdebug，无输出即已禁用
Docker 环境下镜像配置容易漏掉的点
很多人在 Dockerfile 里只写了 RUN composer config -g repo.packagist ...，但构建阶段用的是 composer:latest 镜像，而运行阶段切换成 php:8.2-fpm-alpine 后，这个配置就丢了——因为 composer 是独立容器，它的配置不会自动同步到 PHP 容器里。
立即学习“PHP免费学习笔记（深入）”；
- 正确做法是在 PHP 运行阶段镜像中重新配置，例如：
RUN composer config -g repo.packagist https://mirrors.aliyun.com/composer/ - 或者更彻底：在 PHP 容器启动前，把配置写进
/root/.composer/config.json（对应 root 用户）或/var/www/.composer/config.json（对应 www-data 用户） - 多阶段构建中，若用
COPY --from=composer /app/vendor /var/www/html/vendor，确保构建阶段也用了镜像源，否则 vendor 里包还是从国外拉的
镜像不是一劳永逸的开关，它只是解决连接层问题；真正卡顿还常藏在 PHP 扩展、DNS 解析、甚至本地 hosts 文件污染里。每次 composer install 耗时超过 30 秒，建议先 ping mirrors.aliyun.com 看通不通，再查 php -v 是否带 xdebug，最后才怀疑镜像本身。
