必须重启终端才能使Windows下Composer中文镜像配置生效，因PowerShell/CMD不自动重载%APPDATA%\Composer\config.json；Git Bash路径解析易错；PHPStudy 8.1+无需手动配置；Linux/macOS需避免sudo导致权限错误；项目级配置最可靠，Docker/CI应使用COMPOSER_HOME隔离。
Windows下配置Composer中文镜像的致命细节
Windows用户最常踩的坑不是命令写错，而是改完不重启终端——composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/ 执行后，PowerShell 或 CMD 不会自动重载 %APPDATA%\Composer\config.json，必须关掉当前窗口再新开一个，否则 composer config -g repo.packagist 仍返回空或旧值。
Git Bash 也容易出问题：它可能把 ~/.composer 解析成错误路径，导致配置写到错位置。遇到验证失败时，直接打开 %APPDATA%\Composer\config.json 用记事本确认内容是否为 {"repo":{"packagist":{"type":"composer","url":"https://mirrors.aliyun.com/composer/"}}} 更可靠。
- PHPStudy 用户请忽略手动配置：8.1+ 版本在「工具 → Composer管理」里勾选阿里云镜像后，实际已自动执行正确命令，无需额外操作
- 若提示“PHP版本不匹配”，不是镜像问题，是 PHPStudy 未启用对应版本的 CLI 模块，需在软件界面中开启
- 权限报错（如
Permission denied）大概率因杀毒软件或 Windows Defender 锁定了%APPDATA%\Composer目录，临时禁用实时防护再试
Linux/macOS全局配置必须绕开的权限陷阱
composer config -g 在 Linux/macOS 下默认写入 ~/.composer/config.json，但如果你用 sudo composer config -g，配置会被写进 root 的家目录，而普通用户运行 composer install 时根本读不到——结果就是“明明配了却没生效”。
验证前先确认当前用户：whoami，再检查配置文件归属：ls -l ~/.composer/config.json。如果属主是 root，运行 sudo chown -R $USER:$USER ~/.composer 修复权限，否则清缓存、换镜像都白搭。
- 宝塔面板用户特别注意：面板后台执行命令默认用
www用户，但你的终端登录的是root或普通用户，二者~/.composer完全隔离 - WSL2 用户若从 Windows 启动终端，
~可能指向 Windows 路径，建议统一用$HOME替代~避免路径错乱 - CI/CD 中绝对不要用
-g：Jenkins 或 GitLab Runner 通常以专用用户运行，全局配置会污染其他 job，应改用COMPOSER_HOME隔离
项目级配置才是跨平台真正可靠的方案
全局配置在不同系统上行为不一致，而项目级配置写进 composer.json 后，只要 composer install 能跑通，镜像就一定生效——它不依赖用户家目录、不挑 shell 环境、不受 CI 用户权限干扰。
正确写法只有一种："repositories": {"packagist": {"type": "composer", "url": "https://mirrors.aliyun.com/composer/"}}。注意这里 "packagist" 是 key 名，不是 type 值；type 必须是 "composer"，且 "packagist.org": false **不能加**——加了等于主动切断所有 fallback，镜像站一抖你就卡死。
- 已有私有源？确保
"repositories"是对象（{}），不是数组（[]），否则composer config repo.packagist会报错 - 改完必须运行
composer update --lock，否则composer.lock还记着旧源地址，install 时仍走 packagist.org - 团队协作时，把这个配置提交 Git，新人克隆后无需任何额外操作，
composer install自动走镜像
Docker 和 CI 构建中必须显式指定镜像路径
在 Dockerfile 或 CI 脚本里，composer config -g 不仅无效，还可能污染构建机的全局状态。唯一安全做法是用 COMPOSER_HOME 指向临时目录，并配合 --repository-url 参数强制当次命令走镜像。
示例命令：COMPOSER_HOME=/tmp/composer-home-$$ composer install --repository-url=https://mirrors.aliyun.com/composer/ --no-interaction --optimize-autoloader。其中 $$ 是 shell 进程号，确保并发构建互不干扰。
- 别用
COPY vendor/：宿主机生成的vendor依赖于本地 PHP 版本、扩展和权限，Docker 内直接复制必报错 - CI 中若用
composer require，--repository-url不生效，必须拆成composer config repo.packagist composer https://mirrors.aliyun.com/composer/ && composer require xxx - 腾讯云/华为云镜像可替换 URL，但阿里云同步最稳；
packagist.phpcomposer.com已停用，任何含该域名的日志都说明你还在用废源
