composer中文镜像配置必须同时满足三要素：键名repo.packagist（单数）、显式指定type值为composer、url末尾带/，缺一即静默回退至packagist.org。
不能只改 URL 就算配好中文镜像——漏掉 composer 类型声明或末尾 /，Composer 会静默回退到 packagist.org，你根本不知道它没走镜像。
为什么 composer config -g repo.packagist https://mirrors.aliyun.com/composer/ 没生效？
这是新手最常踩的坑：命令看似执行成功，但 composer install -vvv 日志里依然出现 GET https://packagist.org/。原因只有三个：
-
repo.packagist写成repos.packagist（多一个s）：Composer 2.x 直接忽略，不报错也不写入 - 漏了
composer这个 type 值——正确写法必须是composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/ - URL 缺少末尾
/，比如写成https://mirrors.aliyun.com/composer，请求会变成/composerpackages.json，返回 404
composer create-project codeigniter4/appstarter 必须搭配镜像使用
CI4 的 appstarter 模板依赖大量子包（如 codeigniter4/framework、mikey179/vfsstream），不换源在国内基本卡死或超时。执行前务必确认镜像已生效：
- 运行
composer config -g repo.packagist，输出应为{"type": "composer", "url": "https://mirrors.aliyun.com/composer/"} - 如果输出
null或空，说明配置失败，重跑带composertype 的完整命令 - 安装命令本身加
--prefer-dist --no-interaction可跳过交互、加速下载：composer create-project codeigniter4/appstarter myproject --prefer-dist --no-interaction
项目级镜像比全局更可靠，尤其在 CI/CD 或宝塔环境
全局镜像（-g）在以下场景会失效：
- 项目根目录已有
composer.json且含"repositories": []（哪怕为空数组）：Composer 会直接屏蔽全局设置 - GitHub Actions runner、宝塔后台（
www用户）、Docker 容器中运行命令：读的是对应用户的~/.composer/config.json，和你本地不是同一个文件 - 推荐做法：进项目空目录后，先运行
composer init -n初始化空composer.json，再执行composer config repo.packagist composer https://mirrors.aliyun.com/composer/（去掉-g），它会安全写入composer.json的repositories对象中
换源后仍失败？先清缓存再删 lock 文件
镜像只改下载路径，不解决缓存污染或依赖冲突：
- 必须执行
composer clear-cache：旧缓存里存的是官方源的 hash 和元数据，不清掉，composer update仍可能校验失败 - 删掉
vendor/和composer.lock，再重跑composer create-project：lock 文件中的 hash 是按旧源生成的，和镜像元数据不匹配会导致安装中断 - 验证是否真走镜像：观察
composer install -vvv输出，看到Downloading https://mirrors.aliyun.com/composer/...才算真正生效
CI4 安装本质是骨架初始化，不是“引入依赖”。哪怕镜像配对了，如果跳过 appstarter 直接 require codeigniter4/framework，public/index.php 仍会报 Class 'CodeIgniter\CodeIgniter' not found——目录结构、自动加载、spark CLI 全都依赖 appstarter 提供的完整布局，这点比镜像配置还关键。
