Composer下载失败90%非网络慢，而是配置、权限或环境环节卡死；需据报错关键词逐项验证：DNS/TLS问题切腾讯云镜像并清缓存，扩展缺失查CLI专用php.ini，版本冲突用composer why-not定位，归属权错则修复chown而非chmod。
Composer 下载框架失败，90% 的情况不是网络慢，而是某一个环节卡死在配置、权限或环境上。先看报错关键词，再逐项验证，比反复重试快得多。
报错含 “file could not be downloaded” 或卡在 “Loading repositories”
这是国内用户最常遇到的表象，本质是直连 packagist.org 失败。DNS 污染、TLS 握手中断、连接被重置都会触发，和你本地 PHP 是否装好无关。
- 立刻切腾讯云镜像（2026 年起官方推荐）：
composer config -g repo.packagist composer https://mirrors.cloud.tencent.com/composer/ - 切完必须清缓存：
composer clear-cache，否则旧失败记录还在，重试照样失败 - 加
--prefer-dist强制走 ZIP 包：composer create-project --prefer-dist laravel/laravel myapp，绕过 Git 克隆环节 - 验证是否生效：运行
composer config -g repos.packagist，输出必须是完整 URL（含末尾/），不能是空或packagist.org
报错含 “Class 'Mbstring' not found” 或 “ext-pdo does not exist”
这不是 Laravel 的问题，是 PHP CLI 模式下扩展没加载。网页端 phpinfo() 显示正常，不代表命令行能用——XAMPP、宝塔、Homebrew 用户最容易踩这个坑。
- 运行
php --ini，确认 Loaded Configuration File 是 CLI 对应的php.ini（不是 Apache/Nginx 的） - 编辑该
php.ini，取消注释：extension=mbstring、extension=openssl、extension=pdo、extension=tokenizer、extension=xml、extension=curl - Linux/macOS 用户若用包管理器安装 PHP，需单独装扩展，例如 PHP 8.2：
sudo apt install php8.2-mbstring php8.2-xml php8.2-sqlite3 - 别用
--ignore-platform-reqs掩盖——它会让create-project成功，但后续php artisan key:generate会随机崩
执行 laravel new myapp 提示 “command not found”
说明 ~/.composer/vendor/bin 没进 $PATH，或者该路径本身权限受限。不是没装上，是系统找不到命令。
- 确认 bin 目录位置：
composer config -g bin-dir（默认是~/.composer/vendor/bin） - 把它加进环境变量：在
~/.zshrc或~/.bashrc末尾加export PATH="$HOME/.composer/vendor/bin:$PATH"，然后source ~/.zshrc - 更稳妥方案：改用用户级 bin 目录避开权限纠缠：
mkdir -p ~/bin && composer config -g bin-dir ~/bin && export PATH="$HOME/bin:$PATH" - 验证是否生效：
which laravel应输出路径；ls -la ~/.composer/vendor/bin/应能看到可执行文件且属主是你自己
报错含 “Your requirements could not be resolved”
这表示 Composer 已经连上源、拿到元数据，但在版本求解阶段失败。根本不是网络问题，是依赖约束之间冲突了。
- 运行
composer why-not php:8.3（把 8.3 换成你目标 PHP 版本），直接看到哪个包在拦路，比如laravel/framework v10.42.0 requires php ^8.1，但你项目里还有个包锁死了php: ^7.4 - 检查
composer.json里有没有写死版本号，例如"monolog/monolog": "2.9.0"，而新引入的包要求^3.0，两者无交集 - 打开
composer.lock，查任意包的require.php字段，对比本地php -v输出，版本不匹配就必然失败 - 注意项目级
composer.json中的"config": {"platform": {"php": "8.2.10"}}会强制覆盖本地 PHP 版本判断，删掉或改对再试
真正难排查的是 PHP CLI 和 Web 服务器用了两套 php.ini，或者 ~/.composer 目录被 root 占了但你没意识到——查归属、修归属，别碰 chmod -R 777，那只会让 CI 拒收、Git 报错、后续命令静默失败。
