composer install 不走全局镜像源的根本原因是它只读取项目 composer.json 中的 repositories 字段，忽略全局配置；只要项目中存在 "repositories": [] 或任何非空数组，全局镜像配置即失效。

composer install 为什么没走你配的镜像源

根本原因不是网络或权限，而是 composer install 完全不读全局镜像配置——它只认当前项目的 composer.json 里的 repositories 字段。哪怕你用 composer config --global repos.packagist.org 配得再完美，只要项目里有 "repositories": [] 或任何非空 repositories 数组，全局配置就彻底失效。

常见错误现象：

• 运行 composer config --global repos.packagist.org 输出镜像地址，但 composer install 日志里仍出现 https://repo.packagist.org/packages.json
• 删了 vendor 和 composer.lock 后重装，还是连不上镜像

排查方法：

• 先执行 composer config repositories（不加 --global），看输出是否为空或仅含项目级定义
• 检查项目 composer.json 是否存在 repositories 字段，哪怕值是空数组也要删掉
• 确认 composer.lock 里 packages 条目的 dist.url 是否已指向镜像域名（如 mirrors.aliyun.com）

全局 config.json 路径和写入方式必须严格匹配 Composer 2.0+ 规则

Composer 2.0+ 不再读 ~/.composer/config.json，只认 ~/.config/composer/config.json（Linux/macOS）或 %APPDATA%\Composer\config.json（Windows）。手动编辑文件几乎必然静默失效，必须用命令写入。

验证真实路径：

• 运行 composer config --global --list --verbose，首行即实际加载路径
• 若输出为空，说明 $COMPOSER_HOME 指向无效目录，或权限不足导致写入失败
• 在 Git Bash 中执行 composer config --global 可能因 %APPDATA% 不展开而写入失败，且无提示

正确写法（以阿里云镜像为例）：

Pandas 配置文件报告生成器

使用ydata-profiling（前身为pandas-profiling）生成全面的数据质量报告，包含相关性分析、缺失值模式和基数检测。导出交互式HTML仪表板和JSON摘要。

下载

• composer config --global repos.packagist.org '{"type": "composer", "url": "https://mirrors.aliyun.com/composer/"}'
• 键名必须是 repos.packagist.org（复数 repos，带 .org），不能是 repo.packagist 或 repositories
• 值必须是合法 JSON 字符串，单引号、中文引号、裸 URL 均无效

install 时镜像生效的三个硬性前提

composer install 要真正走镜像，必须同时满足：

• 项目 composer.json 中未声明 repositories 字段（或显式删除该字段）
• 全局配置中 repos.packagist.org 已设为镜像 URL，且格式完全正确
• 执行过 composer clear-cache，否则旧缓存里仍存 packagist.org 的元数据，新镜像不会被查询

容易忽略的细节：

• composer.lock 文件一旦存在，install 就只按里面记录的 dist.url 下载，跟当前镜像配置无关——换镜像前必须删 lock 文件
• 如果 lock 文件里已有包来自 packagist.org，即使你改了全局镜像，install 仍会尝试从原地址下载，404 后才 fallback（如果你没禁用 packagist.org）
• clear-cache 不清理 vendor 目录，但会影响后续 install 对包元数据的解析路径

项目级 repositories 和全局配置的冲突本质

项目级 repositories 不是“叠加”全局配置，而是直接屏蔽。Composer 的逻辑是：有项目级定义 → 忽略全局；无项目级定义 → 才读全局。

典型误操作：

• 为临时测试删掉项目 repositories 字段，跑完 install 后忘了加回去，导致后续 CI 构建失败
• 在团队协作中，有人提交了空 "repositories": []，其他人拉代码后镜像立即失效，却以为是自己本地配置坏了
• 私有源配置写在项目 repositories 里，但没加 {"packagist.org": false}，结果新包没同步时自动回退到官方源，误判为镜像不稳定

真正可控的方式只有两种：

• 纯全局镜像：确保所有项目都不含 repositories 字段，靠 composer config --global 统一管理
• 项目级精确控制：在 composer.json 里显式写全 repositories 数组，把镜像放第一位，末尾加 {"packagist.org": false}，并删掉 vendor 和 composer.lock 后重装

最麻烦的其实是中间态：项目里写了部分 repositories 却漏了 packagist.org 禁用，或者全局和项目都配了但顺序混乱，这种问题查日志都难定位。