composer config -g repo.packagist 命令必须严格满足四点：键名repo.packagist（单数小写）、第三个参数composer为必填type值、URL以/结尾、执行后需composer clear-cache并验证输出及实际请求，任一缺失均导致静默失效。
composer config -g repo.packagist 命令必须写对
直接改 composer.json 或手动编辑 ~/.composer/config.json 容易出错，真正该用的是 Composer 原生命令。换源失败，八成卡在命令拼写上：
-
repo.packagist是正确键名，不是repos.packagist、repo.packagist.org或repositories.packagist - 中间的
composer是 type 字段，**不能省略**，否则会创建无效仓库 - URL 必须以
/结尾，https://mirrors.cloud.tencent.com/composer/✅，https://mirrors.cloud.tencent.com/composer❌（部分 2.2+ 版本报Invalid repository type）
正确执行：
composer config -g repo.packagist composer https://mirrors.cloud.tencent.com/composer/
换完不生效？先清缓存，再验证真实请求
配置写进去了，但 composer install 还是慢、还是连 packagist.org，大概率是缓存没清，或被项目级配置覆盖：
- 必须执行
composer clear-cache，否则 Composer 继续用旧元数据，镜像形同虚设 - 验证是否真生效：
composer config -g repo.packagist输出里要有"url": "https://mirrors.cloud.tencent.com/composer/" - 观察实际请求：
composer show laravel/framework --no-ansi -vvv | grep mirrors，看到腾讯云域名才算数 - 检查项目级覆盖：进项目根目录运行
composer config repos.packagist，若有输出，说明composer.json里写了repositories，它会**完全覆盖**全局设置
项目里有 repositories 字段怎么办
很多老项目或私有包场景会在 composer.json 里显式声明 repositories，比如只加了一个私有源，却意外关掉了 packagist 镜像：
腾讯云harness最佳实践-skills
下载
把一个已有 git 仓库装配成"TAPD 故事 → feature 分支 → PR → CNB AI 代码评审 → 合入 main → TAPD 故事自动回写 commit"的闭环工程挽具（harness）。适用于腾讯云 CNB（cnb.cool）+ TAPD 组合的团队。触发场景：(1) 用户要求把 git 仓库接入 CNB 和/或 TAPD；(2) 要求 commit/PR 自动关联 TAPD 故事；(3) 要求启用 CNB AI 代码评审（cnbcool/ai-review）；(
- 若想保留私有源又走腾讯云镜像，需显式启用 packagist 并设为 false 后重开：
"repositories": {
"private-repo": { "type": "composer", "url": "https://your.private.repo/" },
"packagist": false
}
- 或者更稳妥地，把 packagist 显式写成镜像：
"repositories": {
"private-repo": { "type": "composer", "url": "https://your.private.repo/" },
"packagist": { "type": "composer", "url": "https://mirrors.cloud.tencent.com/composer/" }
}
注意：这种写法优先级高于全局配置，但会污染 composer.json 提交记录。
腾讯云镜像连不上？别硬扛，快速切阿里云或临时绕过
腾讯云镜像本身同步正常，但部分地区（教育网、某些企业防火墙）会拦截 mirrors.cloud.tencent.com，表现为 DNS 解析失败或 HTTPS 握手异常：
- 先试
ping mirrors.cloud.tencent.com，不通就别折腾，直接切阿里云：composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/ - 若 DNS 可通但报证书错误（如
unable to get local issuer certificate），可临时关校验：composer config -g secure-http false（仅调试用，勿长期保留） - CI 或单次调试时，跳过全局改写，用
-r参数最干净：composer install -r https://mirrors.aliyun.com/composer/
镜像地址末尾斜杠、composer 类型字段、缓存清理、项目级覆盖——这四点漏掉任一，都会让切换看起来“成功”实则无效。
