composer config -g repo.packagist 命令必须严格满足三要素：字段名 repo.packagist（非 repos）、type 值为 composer、URL 为 HTTPS 且末尾带 /；否则静默失效，需按实际执行用户配置，项目级配置更安全可靠。
composer config -g repo.packagist 命令必须写对三要素
配不生效，90% 是这条命令敲错了，不是网络问题。它必须同时满足三个硬性条件：
-
repo.packagist不能写成repos.packagist（多一个s就完全无效，也不报错） - 中间的
composer是 type 值，不能省；漏掉它，Composer 2.x 会静默 fallback 到官方源 - URL 必须是 HTTPS 且末尾带
/，例如https://mirrors.aliyun.com/composer/✅，https://mirrors.aliyun.com/composer❌（少斜杠直接 404）
验证是否成功：运行 composer config -g repo.packagist，输出应为完整 JSON 对象，如 {"type": "composer", "url": "https://mirrors.aliyun.com/composer/"}。如果返回空、null 或报错，说明根本没写进去。
全局配置在宝塔、CI 或计划任务里可能不生效
全局配置写在 /root/.composer/config.json，但它只对以 root 用户身份执行的 composer 命令有效。而宝塔面板的「PHP 管理器」或「计划任务」通常以 www 用户运行，根本读不到 root 的配置。
解决方法很直接：
- 先确认实际执行用户：在宝塔终端里运行
whoami，或查计划任务日志里的 UID - 给对应用户配镜像：比如是
www用户，就执行sudo -u www composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/ - CI 环境同理，确保构建脚本中执行
composer config -g和后续composer install是同一个用户
别指望 sudo composer config -g 写进 root 配置后，普通用户就能自动继承——Composer 不做跨用户配置共享。
项目级配置比全局更安全，但别覆盖已有 repositories
项目级配置写入当前项目 composer.json 的 repositories 字段，不干扰其他项目，适合团队协作或 CI/CD 流程中保障一致性。
正确做法是进项目根目录后执行（去掉 -g）：
composer config repo.packagist composer https://mirrors.tuna.tsinghua.edu.cn/composer/
这条命令会自动向 composer.json 的 repositories 中追加 "packagist" 条目，不会清空已有私有源。但注意：
- 如果项目已存在
"repositories": { "my-private": {...} }这类对象结构，命令能安全 merge - 如果
repositories是数组格式（如"repositories": []），命令会报错，需先手动改为对象再重试 - 千万别手写
"packagist.org": false——这会导致连laravel/framework都装不上
换源后首次 install 报 hash 不匹配？删 vendor 和 lock 重来
镜像源和官方源的元数据同步存在极短延迟（通常小于 1 小时）。换源后首次运行 composer install 可能因缓存残留或 lock 文件引用旧哈希而报错，例如：
Invalid package information: The checksum verification of the file failed
这不是镜像不可用，而是本地状态与新源不一致。最稳妥的解法是：
- 删掉
vendor/目录和composer.lock文件 - 重新运行
composer install - 观察日志中下载域名是否变成你配的镜像地址（如
mirrors.aliyun.com）
别试图跳过校验或强制更新——Composer 的 hash 校验机制是安全底线，绕过它等于放弃包完整性保障。
