国内安装 laravel 10/11 必须闭环四步：一配腾讯云/华为云 composer 镜像；二验 php≥8.1（l10）或≥8.2（l11）且 mbstring、openssl、pdo、intl 等扩展真实启用；三用 composer create-project laravel/laravel:^10.0 或 ^11.0 显式锁定版本；四进项目执行 php artisan key:generate && config:clear && cache:clear。
装 Laravel 10 或 11，国内环境最常卡在下载慢、扩展报错、版本不匹配这三块。核心不是“换镜像就完事”，而是镜像 + PHP 环境 + 版本锁定 + 缓存清理四步必须闭环。
一、优先配好 Composer 国内镜像源
阿里云镜像偶尔有包版本滞后（尤其 2026 年初出现过 provider-2024-xx.json 404），推荐用腾讯云或华为云镜像更稳：
- 腾讯云（当前最稳）：composer config -g repo.packagist composer https://mirrors.cloud.tencent.com/composer/
- 华为云（备用）：composer config -g repo.packagist composer https://repo.huaweicloud.com/composer/
- 验证是否生效：composer config -l | grep repo.packagist，输出应含你刚设的 URL
二、PHP 环境必须达标且真实启用扩展
Laravel 10 要求 PHP ≥ 8.1，Laravel 11 强制 PHP ≥ 8.2；只看 php -v 不够，得确认扩展真在运行时加载：
- Linux/macOS：php -m | grep -E "(mbstring|openssl|pdo|tokenizer|xml|ctype|json|intl)"，每项都必须有输出
- 缺 intl（Mac 常见）：brew install php@8.2；Ubuntu/Debian：sudo apt install php-intl
- Windows（XAMPP/Laragon/WAMP）：进控制面板 → 找 PHP 扩展管理 → 勾选 mbstring、openssl、pdo_mysql、tokenizer、xml、ctype、json、intl
- 关键一步：执行 php --ini 查到加载的 php.ini 路径，手动打开检查 extension= 行是否取消注释
三、创建项目时显式指定版本，别依赖默认
直接跑 composer create-project laravel/laravel 极大概率拉到 Laravel 11+ 或 dev 分支，本地 PHP 版本不匹配就会卡死或启动报错：
- Laravel 10（LTS，推荐生产）：composer create-project laravel/laravel:^10.0 myapp
- Laravel 11（需 PHP 8.2+）：composer create-project laravel/laravel:^11.0 myapp
- 若仍卡在 Installing dependencies 或 zlib_decode 报错：
– 清 Composer 缓存：rm -rf ~/.composer/cache（macOS/Linux）或 del /s /q %COMPOSER_HOME%\cache（Windows）
– 加内存限制再试：COMPOSER_MEMORY_LIMIT=-1 composer create-project laravel/laravel:^10.0 myapp
四、初始化后必须清缓存并生成密钥
.env 修改后不清理缓存，APP_KEY 没生成，90% 的白屏/500 错误都源于此：
- 进入项目目录：cd myapp
- 生成应用密钥：php artisan key:generate
- 清除配置与缓存：php artisan config:clear && php artisan cache:clear && php artisan view:clear
- 数据库配置注意：DB_HOST 写 127.0.0.1，别写 localhost（MySQL 8.0+ 默认禁用 socket 连接）
