换源是解决 composer install 卡在 Downloading 的刚性前提；全局换源用 composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/，项目级加 repositories 字段，临时换源用 --repository 参数。
换源不是“可选优化”，是解决 composer install 卡在 Downloading 的刚性前提——90% 的慢，和你家宽带无关，而是还在直连 packagist.org。
全局换源：一条命令立即生效，但必须写对参数
执行 composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/ 即可完成全局配置。这条命令会直接写入 ~/.composer/config.json，所有项目默认走阿里云镜像，无需重启终端、不改任何文件。
- 必须带
-g，否则只影响当前目录（且会写进composer.json，不是你想要的全局效果） -
repo.packagist是 Composer 2.x 的正确 key；Composer 1.x 要用packagist（不带repo.前缀） - URL 必须以
/结尾，https://mirrors.aliyun.com/composer（少斜杠）会 404 - 别写成
repos.packagist（多一个s）或漏掉composer类型声明，否则静默无效
验证是否成功：composer config -g repo.packagist 输出应为 https://mirrors.aliyun.com/composer/ 或 {"type": "composer", "url": "https://mirrors.aliyun.com/composer/"}，不是空、不是 https://packagist.org。
项目级换源：协作更稳，但要注意 JSON 格式和覆盖风险
进项目根目录，运行 composer config repo.packagist composer https://mirrors.aliyun.com/composer/（去掉 -g）。它会自动往 composer.json 的 repositories 字段里追加 packagist 镜像配置，Git 提交后队友拉下来就自动生效。
工作流任务拆解与模型编排技能。使用场景：(1) 收到复杂工作任务需要拆解为可执行步骤，(2) 需要为不同步骤选择最合适的模型，(3) 需要跟踪工作流进度和模型使用情况，(4) 长时间任务卡住需要问题诊断和解决方案。
- 如果项目已有
repositories字段（比如含私有包源），这条命令会安全追加，不会误删原有配置 - 手动编辑
composer.json时，必须保证 JSON 合法："repositories": [{"type":"composer","url":"https://mirrors.aliyun.com/composer/"}] - 千万别加
"packagist": false，否则基础包（如monolog/monolog）都拉不到 - 项目级配置优先级高于全局，适合需要统一环境的团队，也方便 CI 脚本复现
临时换源：调试和 CI 场景首选，但参数名不能错
只想试一次、不想污染环境、或排查为什么还是慢？用 --repository 参数：
- 正确写法：
composer install --repository=https://mirrors.aliyun.com/composer/ - 错误写法：
--repository-url、--mirror、--source—— Composer 不认，会静默忽略 - 加
-vvv可看到真实请求 URL：composer update -vvv --repository=https://mirrors.cloud.tencent.com/composer/，一眼确认是否走镜像 - 注意：
composer require不支持--repository，它只对install、update、create-project生效 - 临时参数优先级最高，会覆盖全局和项目级配置，但也仅限当次命令
换源后仍慢？这些点常被忽略
镜像只加速下载，不解决依赖解析卡顿。如果 composer update 卡在 Resolving dependencies，和镜像无关，得看本地 PHP 版本、内存限制或 lock 文件状态。
- 换源后务必运行
composer clear-cache，否则旧缓存可能继续拉取海外元数据 - Composer 2.2+ 默认开启官方源 fallback：镜像返回 404/503 时会自动切回
packagist.org，别轻易关掉（如composer config -g repos.packagist false） - 新发布的包可能有 5–30 分钟同步延迟，镜像站底部通常标有“最后更新时间”，别急着换源或关 fallback
- 宝塔面板用户注意：
-g写的是当前用户（如root）配置，但 PHP 管理器常以www用户运行，需额外给www用户也配一次
最易踩的坑不是命令写错，而是换源后没清缓存、没验证输出、或误以为镜像能解决所有慢——它只管下载，不管解析、不替你升级 Composer 版本、也不绕过私有仓库的网络路径。
