必须用composer config --global修改，手动编辑config.json几乎必然静默失效；确认真实路径需运行composer config --global --list --verbose，首行即实际加载的config.json路径，优先读$COMPOSER_HOME，其次默认路径，且Composer 2.0+只认~/.config/composer/config.json而非~/.composer/config.json。
必须用 composer config --global 命令修改，手动编辑 config.json 文件几乎必然静默失效。
怎么确认当前生效的全局配置路径
Composer 不读你“以为”的那个文件。它优先检查 $COMPOSER_HOME 环境变量，其次才是默认路径（Linux/macOS 是 ~/.config/composer/config.json，Windows 是 %APPDATA%\Composer\config.json）。但多个路径可能共存，而 Composer 只认一个。
运行这条命令才能看到真实加载的文件：
composer config --global --list --verbose
输出第一行就是实际读取的 config.json 路径。常见误判包括：
-
~/.composer/config.json和~/.config/composer/config.json同时存在 → Composer 2.0+ 只读后者，前者被忽略 - 在 Git Bash 中执行
composer config --global→%APPDATA%不展开，写入失败却不提示 - 设置了
COMPOSER_HOME但指向空目录或权限不足 → 写入静默失败，config --global --list输出为空
改镜像源后为什么 composer install 还走官方源
根本原因不是网络问题，而是键名、结构或缓存没处理对。国内用户最常卡在这三点：
- 键名必须是
repos.packagist.org（复数repos，带.org），不是repo.packagist或mirror—— 拼错一个字符就无效 - 值必须是完整 JSON 对象字符串：
{"type": "composer", "url": "https://mirrors.aliyun.com/composer/"}，不能只写 URL 字符串，也不能用单引号或中文标点 - 设完必须运行
composer clear-cache，否则旧缓存里的包索引还在，新镜像根本没机会用上
验证是否生效：
composer config --global repos.packagist.org
应输出完整 JSON 对象；若返回空或 {"type": "composer", "url": "https://packagist.org"}，说明没生效。
哪些配置项必须加 --global 才有效
不是所有配置都支持全局作用域。以下字段漏掉 --global 就等于白配，项目级写入完全无效：
-
github-oauth.github.com：GitHub 令牌，用于绕过 API 限流，项目级设了也忽略 -
http-basic.repo.example.com：私有仓库 HTTP 认证，漏掉--global就只影响当前项目 -
bin-dir：指定composer global require安装的可执行文件存放路径，例如~/.local/bin，改完记得把该路径加进$PATH -
store-auths：控制是否保存认证凭据，默认true，设为false则每次都要输密码
注意：process-timeout、cache-dir 等字段虽支持全局，但值必须用引号包裹（如 "300"），否则含空格或特殊字符时会被截断。
改完不生效？先查这三件事
配置变更后，composer update 不会自动重读全局设置。遇到“明明改了却没用”，优先排查：
- 是否被项目级
composer.json的config或repositories字段完全覆盖？项目配置优先级高于全局，且是“替换”而非“合并” - 是否在错误终端执行？PowerShell、CMD、Git Bash 的环境变量不共享，改完需新开对应终端再验证
- 是否以 root/sudo 执行过
composer config --global？可能导致配置写入了 root 用户目录，普通用户运行时读不到
最稳的做法：每次修改后，立刻跑 composer config --global --list 确认内容，再跑 composer clear-cache，最后用 composer require monolog/monolog -vvv 观察实际请求的 URL 是否已切换。
