旧版ThinkPHP（5.0/5.1）必须用项目级镜像配置并显式禁用packagist.org回退，即执行composer config repo.packagist composer https://mirrors.aliyun.com/composer/后，在composer.json的repositories首位添加{"packagist": false}，再删除vendor和composer.lock，运行composer install --no-dev --prefer-dist。
旧版 ThinkPHP（如 5.0/5.1）项目能用中文镜像，但必须绕过 Composer 2.x 的 strict 检查，且不能依赖 composer update 自动降级——否则会报 package not found 或卡死在 resolving。
旧版 ThinkPHP 项目必须用项目级配置，全局镜像基本无效
ThinkPHP 5.0–5.1 多数运行在 PHP 7.1–7.3 环境，而这些环境常由宝塔、Docker 或 CI 以非 root 用户（如 www）启动，它们根本读不到你本地 ~/.composer/config.json。全局配置 composer config -g repo.packagist 在这类场景下等于没配。
- 进项目根目录（确保有
composer.json），执行：composer config repo.packagist composer https://mirrors.aliyun.com/composer/（注意：不带-g） - 该命令会自动在
composer.json的repositories字段安全追加，不会覆盖已有私有源 - 如果
composer.json原本是"repositories": {}，命令会转为标准数组并插入；如果是"repositories": []，则追加到末尾 - 切勿手动编辑 JSON —— 少一个逗号或引号，
composer install直接报错退出
Composer 2.x 需显式禁用 packagist.org 回退机制
旧版 ThinkPHP 项目依赖的包（如 topthink/framework 5.1.x）在阿里云镜像中同步较慢，Composer 2.x 默认开启 packagist.org 自动回退，一旦镜像暂未同步，它会悄悄切回海外源，导致下载失败或超时，且不提示。
- 执行项目级配置后，必须手动编辑
composer.json，在repositories数组首位添加：{"packagist": false} - 完整示例（注意顺序和逗号）：
"repositories": [
{"packagist": false},
{"type": "composer", "url": "https://mirrors.aliyun.com/composer/"}
]
- 这个
{"packagist": false}是硬性开关，告诉 Composer “别 fallback”，否则镜像失效时你完全感知不到 - 改完立刻删掉
vendor/和composer.lock，再跑composer install --no-dev --prefer-dist
避免 composer update 导致版本爆炸或解析卡死
旧版 ThinkPHP 项目 composer.json 中常含宽泛约束（如 "php": ">=5.6.0"、"topthink/framework": "^5.1"），Composer 2.x 在解析时会尝试遍历大量历史版本，极易卡在 Resolving dependencies 阶段，这不是镜像问题，而是约束失控。
立即学习“PHP免费学习笔记（深入）”；
- 禁止直接运行
composer update—— 它会无视 lock 文件，重新解空间，大概率失败 - 只允许用
composer update topthink/framework --with-dependencies升级指定包 - 若需新增依赖，先收紧 PHP 版本约束，例如改为
"php": "7.2.* || 7.3.*" - 删除
require-dev中所有非必需项（如phpunit/phpunit无版本号的写法），或直接清空该字段再加--no-dev
验证镜像是否真在生效，别信 composer diagnose
composer diagnose 只检查语法和本地连通性，完全不验证镜像源是否被实际调用。旧版项目尤其容易“看着配好了，其实还在连 packagist.org”。
- 最可靠验证方式：运行
composer config repo.packagist（不带-g），输出必须是完整 JSON：{"type": "composer", "url": "https://mirrors.aliyun.com/composer/"} - 若返回空、
null或报Key not found，说明配置没写进当前项目，立刻重试composer config repo.packagist ... - 临时强制走镜像测试：运行
composer show topthink/framework --repository-url=https://mirrors.tuna.tsinghua.edu.cn/composer/，能列出版本即证明镜像可用 - 注意：换源后首次
install仍可能慢几秒——这是 Composer 在初始化元数据缓存，不是失败
旧版 ThinkPHP 维护中最容易被忽略的是 {"packagist": false} 这一行，它不写，镜像就形同虚设；写了却不删 composer.lock，旧缓存会继续拉错包。这两步漏掉任意一个，都会让整个配置白忙活。
