Laravel 10+ 要求 PHP ≥ 8.1 并启用 mbstring、openssl、pdo、tokenizer、xml、ctype、json、intl 扩展；Mac 用户易缺 intl，Windows 用户常缺 opcache；需检查版本与扩展、配置国内 Composer 镜像、正确设置 .env 中 APP_KEY、DB_DATABASE、APP_URL，并清缓存后访问 http://localhost:8000 验证。
确认系统是否满足 Laravel 运行要求
Laravel 10+ 要求 PHP ≥ 8.1，且必须启用 mbstring、openssl、pdo、tokenizer、xml、ctype、json 这些扩展。Mac 用户用 Homebrew 安装 PHP 后常漏掉 intl 扩展，导致 composer create-project 卡在依赖解析阶段；Windows 用户用 XAMPP/WAMP 时默认不带 php-opcache，后续运行 php artisan serve 会慢得明显。
- 运行
php -v检查版本，低于 8.1 就别硬上 Laravel 10 - 执行
php -m | grep -E 'mbstring|openssl|pdo|tokenizer|xml|ctype|json|intl'（Linux/macOS）或php -m（Windows）逐个核对 - 若缺
intl，Ubuntu/Debian 执行sudo apt install php-intl；macOS Homebrew 用户执行brew install php@8.2（自动带全扩展）
用 Composer 创建 Laravel 项目时绕过常见卡点
composer create-project laravel/laravel 命令失败，90% 是因为 Composer 镜像源未切国内或内存限制不足。Laravel 10 的 vendor 目录下载量超 150MB，GitHub 原源在部分地区超时或被重置连接。
- 先执行
composer config -g repo.packagist composer https://packagist.phpcomposer.com（旧镜像）或更推荐的composer config -g repo.packagist composer https://packagist.org+ 配置国内 DNS（如 114.114.114.114） - 临时提高内存：运行
COMPOSER_MEMORY_LIMIT=-1 composer create-project laravel/laravel blog - 如果提示
zlib_decode(): data error，说明压缩包损坏，删掉~/.composer/cache后重试
配置 .env 文件前必须改的三项
新项目跑起来前，.env 不只是改数据库密码那么简单。APP_KEY、DB_DATABASE 和 APP_URL 这三项填错，会导致路由 404、登录态失效、邮件发不出等隐性问题。
-
APP_KEY必须用php artisan key:generate生成，手输或复制旧项目的值会导致加密 session 失效 -
DB_DATABASE填的是数据库名，不是用户名；MySQL 默认 root 用户无密码，但 Laravel 默认配置里DB_PASSWORD=是空字符串，不能留空或写null -
APP_URL影响 CSRF token 和邮箱链接生成，开发时设为http://localhost:8000，别用127.0.0.1—— Chrome 对 localhost 和 IP 视为不同源，跨域请求会失败
启动开发服务器并验证是否真跑通
php artisan serve 成功输出 “Server started” 并不等于 Laravel 已就绪。浏览器打开后空白或报 Target class [App\Http\Controllers\HomeController] does not exist 很常见，本质是路由缓存或控制器命名空间没对齐。
- 首次启动前先清缓存：
php artisan config:clear && php artisan cache:clear && php artisan view:clear - 访问
http://localhost:8000出现 Laravel 欢迎页才算基础环境 OK；若报 500 错误，立刻看storage/logs/laravel.log最末几行，90% 是.env中某项格式错误（比如多了一个空格或用了中文引号） - 如果页面加载极慢（>10s），检查是否启用了 Xdebug —— Laravel 开发时建议关闭，或至少把
xdebug.mode=off加入php.ini
真正麻烦的是混合部署场景：比如用 Valet 但本地又装了 Apache，端口冲突不报错只静默失败；或者 Docker 启动了 MySQL 容器但 Laravel 还连着宿主机的 3306。这类问题不会出现在安装指南里，只能靠 netstat -tuln | grep :8000 和 php artisan tinker --execute="echo env('DB_HOST')" 一层层剥。
