Composer中文镜像不是提速插件而是可用性底座，未配置则在国内大概率卡死在Downloading或报Connection timeout、403；根源常是配置未生效——键名必须为repo.packagist（单数）、type必填composer、URL末尾带/，且项目级repositories会覆盖全局配置。
Composer中文镜像不是“提速插件”，而是工具链的可用性底座
没配中文镜像的 Composer，在国内基本跑不起来——不是慢，是大概率卡死在 Downloading 或直接报 Connection timeout、403 Forbidden。这不是性能问题，是连通性断点。AI 编程助手（如 Aider）调用 composer install 失败、CI 流水线反复重试、本地 composer update 卡住半小时，根源往往就在这里。镜像解决的不是“快不快”，而是“能不能走通”。一旦这条通道堵死，整个 PHP 工具链——从代码生成、依赖安装、自动加载到 CI 构建——都会在第一步就失效。
为什么 Docker / CI / 宝塔里镜像经常“配了等于没配”
镜像配置写对了，但执行环境根本读不到，这是最常被忽略的落地断层：
-
composer config -g写的是当前用户的~/.config/composer/config.json，而 Docker 构建阶段、GitHub Actions runner、宝塔后台任务默认以www或非 root 用户运行，压根不读 root 下的配置 - Dockerfile 里
COPY ~/.composer/config.json没用：容器启动时该路径不存在，且构建阶段用户上下文和运行阶段不一致 - GitHub Actions 必须缓存
~/.composer目录，否则每次都是干净环境，全局配置丢失 - K8s Job 或 Jenkins Agent 若未挂载
COMPOSER_HOME或未指定运行用户，composer config -g的写入直接被丢弃
项目级配置比全局配置更可靠，但要注意格式陷阱
想让配置真正生效且可复现，优先用项目级方式：composer config repo.packagist composer https://mirrors.aliyun.com/composer/（去掉 -g）。它会安全写入当前项目的 composer.json 的 repositories 字段，但有三个硬性前提：
工作流任务拆解与模型编排技能。使用场景：(1) 收到复杂工作任务需要拆解为可执行步骤，(2) 需要为不同步骤选择最合适的模型，(3) 需要跟踪工作流进度和模型使用情况，(4) 长时间任务卡住需要问题诊断和解决方案。
- 项目
composer.json中的repositories必须是对象（{}），不能是空数组（[]），否则命令失败 - 如果已有私有源，该命令只追加
"packagist": {"type": "composer", "url": ".../"}子项，不会覆盖其他源 - URL 末尾必须带斜杠（
/），否则请求路径拼成/composerpackages.json→ 404 → 静默 fallback 到官方源 - 键名必须是
repo.packagist（单数），写成repos.packagist（复数）完全无效，且无任何提示
换镜像后仍卡在 “Loading composer repositories” 怎么排查
这不是镜像没生效，而是请求根本没发过去。典型表现是 composer install -vvv 输出里没有 GET https://mirrors.xxx.com/composer/，只有 GET https://packagist.org/ 或长时间停在解析阶段：
- 检查是否被项目级
repositories覆盖：运行composer config --list，确认repo.packagist值是你设的 URL - 看
composer.json是否含"packagist.org": false这类禁用语句，它会直接屏蔽所有 packagist 行为 - 执行
composer clear-cache，再重试；旧缓存可能残留旧源地址 - 若用自建镜像（如
packagist-mirror），确认服务已启动且能被容器/CICD 网络访问，curl -I http://mirror.internal/composer/packages.json应返回 200
真正容易被忽略的，是镜像配置本身不报错，但只要键名、type、URL 格式三者中任一出错，就静默失效——你看到的仍是 packagist.org，却不知道它早已被绕开。
