根本原因是PHP版本<8.1、必需扩展未启用、Composer镜像源未切国内、.env修改后未清缓存；须依次验证PHP≥8.1及mbstring/openssl/pdo等扩展、指定laravel/laravel:^10.0安装、生成APP_KEY并执行config:clear/cache:clear、DB_HOST设为127.0.0.1。
直接跑 composer create-project laravel/laravel 很大概率失败或启动后报错——根本原因不是命令写错了，而是 PHP 版本、扩展、镜像源、.env 缓存这四层没对齐。
检查 PHP 版本与必需扩展是否真实启用
Laravel 10+ 强制要求 PHP ≥ 8.1，且 mbstring、openssl、pdo、tokenizer、xml、ctype、json、intl 必须全部加载。只看 php -v 不够，得确认扩展真在运行时生效。
- Linux/macOS：运行
php -m | grep -E "(mbstring|openssl|pdo|tokenizer|xml|ctype|json|intl)"，每项都应有输出；缺intl（Mac 常见）就装：brew install php@8.2（Homebrew 用户）或sudo apt install php-intl（Ubuntu/Debian） - Windows：用 XAMPP/Laragon 时，进控制面板打开对应扩展；若用 WAMP，右键托盘图标 → PHP → PHP extensions → 勾选上述模块
- 别信“已安装”，执行
php --ini找到实际加载的php.ini路径，手动检查extension=行是否取消注释
用 Composer 拉取指定 LTS 版本并绕过卡死
默认命令拉的是最新版，可能依赖 PHP 8.4 或 MySQL 8.3，本地环境不匹配就卡在 Installing dependencies。必须锁定 Laravel 10（当前 LTS），同时换国内镜像源。
- 先全局配阿里云镜像：
composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/ - 创建项目时显式指定版本：
composer create-project laravel/laravel:^10.0 myapp（别省略^10.0） - 若仍卡住或报
zlib_decode(): data error，删缓存重试：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 后必须清缓存才能生效
.env 文件只在首次启动时读取一次，后续全靠缓存驱动。改完 APP_DEBUG=true 却还是 500 错误页面？大概率是缓存没清。
- 复制模板：
cp .env.example .env - 编辑
.env，确保这三项准确：APP_ENV=local、APP_DEBUG=true、APP_URL=http://localhost:8000（别用127.0.0.1，Chrome 视为不同源） - 生成密钥：
php artisan key:generate（APP_KEY为空时才写入，手输或复制旧值会导致 session 失效） - 立刻清缓存：
php artisan config:clear && php artisan cache:clear——跳过这步，.env修改等于白改
启动服务前确认端口与数据库凭据
php artisan serve 报 Address already in use 或页面空白，90% 是端口冲突或 MySQL 凭据错位，不是 Laravel 本身问题。
- 查端口占用：
lsof -i :8000（macOS/Linux）或netstat -ano | findstr :8000（Windows），杀掉 PID 或直接换端口：php artisan serve --port=8001 - MySQL 连接失败（
SQLSTATE[HY000] [1045]）：重点核对.env里DB_HOST=127.0.0.1（别写localhost）、DB_DATABASE=laravel（库名必须已存在）、DB_PASSWORD=（XAMPP/Laragon 默认为空，不能填root或留空不写） - 首次启动前务必执行：
php artisan migrate（否则表结构缺失，登录页都打不开）
最易被忽略的点是：改完 .env 后没清缓存，或 DB_HOST 写成 localhost 导致 MySQL 走 Unix socket 而 Laravel 尝试走 TCP。这两个细节一错，整个流程就卡在“能访问但功能异常”的静默状态。
