必须先执行composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/设置阿里云镜像源，再运行composer clear-cache清缓存，否则直连packagist.org易因网络延迟报“could not find package”或卡在Downloading。
ThinkPHP新手在执行composer create-project topthink/think tp-demo时卡在Downloading或直接报错“could not find package”，八成是因为Composer还在直连海外packagist.org——物理距离+防火墙导致TLS握手慢、首字节延迟高、甚至503超时，和你家宽带无关。
全局镜像配置（新手首选）
这一步操作起来很简单，直接在终端里敲一条命令就能让所有新项目自动走阿里云镜像，不用改文件、不用重启终端。
第一步：打开终端（Windows用户请用PowerShell或CMD，macOS/Linux用自带终端）。
第二步：执行全局镜像设置命令：composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/。
立即学习“PHP免费学习笔记（深入）”；
【必须严格满足三要素：键名是repo.packagist（不能多s或少repo.）、中间的composer是type值不可省、URL末尾必须带斜杠】。漏掉任意一个，命令会静默失效——不报错，但查composer config -g repo.packagist时输出为空或仍是https://packagist.org。
第三步：验证是否生效，运行composer config -g repo.packagist，输出应为{"type": "composer", "url": "https://mirrors.aliyun.com/composer/"}或至少是完整URL字符串；如果返回空、null或报Key不存在，说明没写进去，立刻检查拼写和斜杠。
项目级镜像配置（团队协作/CI必备）
当你把代码推到Git、交给同事或CI流水线构建时，全局配置靠不住——宝塔默认以www用户运行，GitHub Actions用runner用户，它们根本读不到你本地root的配置。这时必须把镜像写进项目本身。
方法一：自动安全写入（推荐）
进入ThinkPHP项目根目录（含composer.json），执行：composer config repo.packagist composer https://mirrors.aliyun.com/composer/。这条命令会自动在composer.json的repositories字段里追加镜像源，不覆盖已有私有包源，也不破坏JSON格式。
方法二：手动编辑（仅当熟悉JSON语法）
打开composer.json，在顶层添加"repositories"字段，确保它是数组形式，首位对象为：{"type": "composer", "url": "https://mirrors.aliyun.com/composer/"}，且"packagist": true（千万别写"packagist": false，否则基础包全拉不到）。
注意：改完必须删掉项目里的vendor/目录和composer.lock文件，再执行composer install（不是update），否则旧lock文件里的hash可能和镜像元数据不匹配，导致安装失败。
临时镜像切换（故障排查专用）
当你怀疑全局或项目配置失效、或者只想快速验证某个镜像是否可用时，用临时参数最干净——它不改任何配置文件，执行完即消失，安全性高。
在项目根目录下，直接运行：composer install -vvv --repository-url=https://mirrors.tuna.tsinghua.edu.cn/composer/。
【-vvv是关键，它会打印真实请求地址，比如看到GET https://mirrors.tuna.tsinghua.edu.cn/composer/p2/topthink/framework.json才算真正走镜像】。
这个参数只对install、update、require命令生效，对create-project也有效，例如：composer create-project topthink/think tp-demo --repository-url=https://mirrors.aliyun.com/composer/。
加速ThinkPHP初始化的三项硬核操作
换镜像只能加速下载环节；如果卡在Resolving dependencies，说明问题出在本地约束太宽、脚本太多或内存不足——必须同步做这三件事。
① 清缓存防污染：composer clear-cache。旧缓存可能残留已下线包的引用，导致回退搜索。
② 禁用dev依赖：--no-dev跳过phpunit、phpstan等大体积开发包，省下40%+时间。
③ 关闭安装脚本：--no-scripts避免post-autoload-dump等脚本因权限或路径失败中断安装，比如清runtime/目录失败直接卡死。
完整推荐命令：composer install --no-dev --no-scripts --no-autoloader --prefer-dist。装完再单独跑composer dump-autoload -o生成优化后的自动加载文件。
