修改composer.json本身不能启用镜像，必须通过composer config命令写入config字段（项目级）或全局配置文件；关键配置项为repo.packagist，需严格匹配键名、type值composer及末尾带/的HTTPS URL，否则静默失效。
修改 composer.json 本身不能启用镜像
很多人误以为改项目根目录下的 composer.json 就能切镜像，其实不行。Composer 镜像配置属于全局或仓库级设置，不写在项目 composer.json 里。真正起作用的是 config 命令写入的配置，它会存到 composer.json 的 "config" 字段（仅对当前项目）或全局配置文件（对所有项目）。
用 composer config 设置国内镜像的两种方式
推荐直接运行命令，避免手动编辑出错。注意区分作用域：
- 仅当前项目生效：
composer config repo.packagist composer https://mirrors.aliyun.com/composer/
- 全局生效（影响所有项目）：
composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/
阿里云镜像稳定、同步及时，清华源（https://packagist.phpcomposer.com）已停用，别再用。执行后可运行 composer config repo.packagist 验证是否写入成功。
为什么 repo.packagist 是关键配置项
Composer 从 2.0 开始默认禁用 packagist.org 的直接访问，必须显式声明 repo.packagist 才能使用镜像。只改 packagist.org 的 URL 或加 http-basic 没用。这个配置项名不能拼错，常见错误包括：
使用ydata-profiling（前身为pandas-profiling）生成全面的数据质量报告，包含相关性分析、缺失值模式和基数检测。导出交互式HTML仪表板和JSON摘要。
- 写成
packagist.org（少repo.前缀） - 写成
packagist（漏掉.packagist） - 值不是完整 HTTPS 地址（比如少了
https://）
错误会导致 composer install 报 Could not fetch packages 或直接 fallback 到官方源（超时失败）。
临时切换镜像比永久配置更安全
如果只是单次安装或 CI 环境，建议用环境变量临时覆盖，避免污染本地配置：
COMPOSER_REPO_PACKAGIST=https://mirrors.aliyun.com/composer/ composer install
这种方式不会写入任何配置文件，适合脚本、Docker 构建或多人共用开发机的场景。但要注意：PHP CLI 环境变量在某些 IDE 或 GUI 终端中可能未继承，优先在纯终端里测试。
镜像配置看似简单，但路径拼写、作用域范围、Composer 版本差异这三点最容易卡住人。改完记得清缓存：composer clear-cache，否则旧包可能仍从原源拉取。
