composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/ 是正确配置 Laravel 国内镜像源的核心命令，必须严格匹配键名、type 值、HTTPS 协议及末尾斜杠，否则缓存不命中或静默失效；验证需输出完整 JSON，空或报错即失败。
composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/ 这条命令就能让 Laravel 项目依赖安装从“等得怀疑人生”变成“秒出 vendor”。不是玄学，是必须做的基础配置。
为什么 Laravel 的 composer install 总卡在 Downloading packages.json
根本不是你家宽带慢，而是 Composer 默认直连 packagist.org —— 它的 DNS 解析、TLS 握手、CDN 节点全在国外。国内用户请求时，经常卡在元数据拉取阶段（比如 provider-laravel~10.0.json），而不是后面下载 ZIP 包。镜像源必须配对 repo.packagist 这个键，否则只改 repositories 字段没用，Composer 2.x+ 会绕过它硬连官方源。
常见错误现象：
-
composer config -g repos.packagist ...（多写了一个s，完全无效但不报错） -
composer config -g repo.packagist https://...（漏掉composer类型声明，旧版 fallback 到官方源） - URL 用
http://或末尾没斜杠 → 404
验证是否生效，直接运行：composer config -g repo.packagist。输出必须是类似 {"type": "composer", "url": "https://mirrors.aliyun.com/composer/"} 的 JSON，空、null 或只输出 https://packagist.org 都算失败。
composer create-project laravel/laravel 还是慢？预置镜像才管用
这个命令分两步：先拉骨架模板，再进目录跑 composer install。如果全局镜像没提前配好，第一步仍可能从官方源读元数据，导致开头就卡住。
实操建议：
- 执行
composer global require laravel/installer前，确保已运行过composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/ - 新建项目时加
--repository参数强制走镜像：composer create-project laravel/laravel demo --repository=https://mirrors.aliyun.com/composer/ - 别用
--repository-url或--mirror—— Composer 不识别，会静默忽略
注意：--repository 优先级最高，会覆盖项目里已有的 repositories 配置，私有包可能找不到，CI 脚本里慎用。
缓存不命中的三个隐藏开关：PHP 版本、平台配置、镜像源一致性
Laravel 项目频繁重装依赖却没走缓存，大概率不是缓存坏了，而是这三个条件没对齐：
-
PHP小版本要固定（如8.3.5），升级到8.3.6后缓存自动失效 -
platform配置需显式声明（尤其在 Docker 中）："config": {"platform": {"php": "8.3.5"}}，否则不同环境解析出的依赖树可能不一致 - 换镜像后必须保证
repo.packagistURL 和缓存里记录的完全一致（含末尾斜杠、协议、域名），哪怕只是换了腾讯云镜像，旧缓存也作废
检查当前缓存路径：composer config -g cache-dir；确认缓存启用：composer config -g cache-files-dir（若为空，补上 composer config -g cache-files-dir ~/.composer/cache/files）。
并发下载调到 15，但别碰 classmap-authoritative
composer config -g parallel-downloads 15 能明显压满带宽，阿里云/腾讯云镜像基本不触发限流。设成 20+ 反而容易 DNS 超时或连接被拒。
但别乱开 --classmap-authoritative 或全局配置 classmap-authoritative: true。它会让 Composer 认为所有类都在 classmap 里，跳过 PSR-4 自动加载扫描——这对 Laravel 的服务提供者发现机制有干扰，可能导致某些包的 ServiceProvider 不被加载。
真正该开的是 --optimize-autoloader（或 -o），它把 PSR-4 映射转成静态数组，不破坏发现逻辑，实测 autoload 阶段快 30%+。
镜像不是万能胶，它只加速网络层。如果 composer update 卡在 Resolving dependencies，问题出在 composer.json 的约束太松（比如 "php": "^7.4 || ^8.0"）、require-dev 塞了太多工具链，或者本地 PHP 扩展缺失。这些和镜像源无关，得另查。
