正确命令是composer config -g repo.packagist composer https://mirrors.cloud.tencent.com/composer/，必须严格满足键名准确、显式声明type值、url末尾带斜杠，否则composer 2.2+会静默回退至官方源且不报错。
composer config -g repo.packagist 命令必须写对三要素
配腾讯云镜像失败，90% 是因为 composer config -g repo.packagist 这条命令敲错了——它不报错，但完全不生效。必须同时满足：键名是 repo.packagist（不能多一个 s）、中间 composer 是 type 值（不是可选参数）、URL 用 HTTPS 且末尾带 /。
-
repo.packagist写成repos.packagist或repositories.packagist→ 静默忽略 - 漏掉
composer（比如写成composer config -g repo.packagist https://mirrors.cloud.tencent.com/composer/）→ fallback 回官方源 - URL 少了末尾
/（如https://mirrors.cloud.tencent.com/composer）→ 拼出错误路径，返回 404 或 Invalid repository type
正确命令只有一条：
composer config -g repo.packagist composer https://mirrors.cloud.tencent.com/composer/
验证是否真走腾讯云镜像，别只看 config 输出
composer config -g repo.packagist 显示 URL 不等于生效。它可能输出 JSON，但实际请求仍打向 packagist.org——常见于缓存未清、项目级配置覆盖或代理干扰。
- 先运行
composer config -g repo.packagist，确认输出是{"type":"composer","url":"https://mirrors.cloud.tencent.com/composer/"} - 再执行
composer show monolog/monolog -vvv 2>&1 | grep "Downloading"，日志里必须出现mirrors.cloud.tencent.com - 如果没出现，检查是否在项目根目录下误执行了
composer config repo.packagist（无-g），它会覆盖全局配置 - 检查
echo $http_proxy（Linux/macOS）或set http_proxy（Windows），代理会劫持所有请求
换源后 vendor 安装失败？删 lock 和 vendor 再重来
镜像只改下载地址，不兼容旧 composer.lock 文件里的哈希值。换源后直接 composer install，大概率报 hash does not match 或卡在 TLS 握手。
- 执行
composer clear-cache清掉本地元数据缓存（尤其p2/目录下的旧索引） - 手动删除
vendor/目录和composer.lock文件 - 运行
composer install --no-cache，强制从新镜像拉取并生成新 lock - 别试图保留旧
composer.lock并修改 URL 字段——Composer 不认这种手动改法
项目级配置比全局更稳，尤其 CI/CD 和团队协作
全局配置写在 ~/.composer/config.json，但在 Docker 构建、宝塔部署、CI runner 环境中，用户权限不同，root 配的别人根本用不上。项目级配置写进 composer.json，拉代码即生效，行为一致。
- 进入项目根目录，运行
composer config repo.packagist composer https://mirrors.cloud.tencent.com/composer/（注意不加-g） - 该命令自动向
composer.json的repositories数组追加"packagist"条目，不会覆盖已有私有源 - 如果项目已有
"repositories": {}，别手动编辑 JSON——格式错一个逗号就让composer install报错 - CI 构建时，容器每次启动都读取最新
composer.json，无需额外 setup 步骤
腾讯云镜像本身稳定，问题几乎全出在本地配置细节或缓存残留上。键名、type、URL 斜杠、缓存清理、lock 文件重建——这五点漏掉任意一个，都会让你以为“镜像没用”。
