composer create-project 是唯一可靠入口，它自动拉取完整骨架、安装依赖、生成 .env 和 APP_KEY；而 composer init + require 会漏掉目录结构、artisan 入口及初始化脚本，导致 Class not found 或命令缺失等错误。
composer create-project 是唯一可靠入口
别用 composer init + composer require laravel/framework 手动搭 Laravel 项目——这会漏掉 artisan、routes/、app/Providers/AppServiceProvider.php 等骨架文件，也跳过 .env 生成和密钥初始化。Laravel 不是普通 Composer 包，它依赖预置的目录结构和脚本钩子（比如 @php artisan package:discover），这些只有 create-project 能自动完成。
常见错误现象：php artisan serve 报错 Class 'Illuminate\Support\Facades\Storage' not found，或运行 php artisan key:generate 提示找不到命令——本质是骨架缺失，不是扩展没装。
-
composer create-project laravel/laravel my-app：拉取最新稳定版（当前为 Laravel 10.x） -
composer create-project laravel/laravel my-app "^11.0@rc"：明确指定 RC 版，避免 fallback 到 v10 -
composer create-project laravel/laravel my-app "dev-main"：用开发主线，适合尝鲜但不稳定
Laravel 11 的 PHP 和扩展硬性门槛
Composer 在解析依赖时会严格校验 laravel/framework 的 "php": "^8.2" 声明。PHP 版本低于 8.2 或关键扩展缺失，create-project 会在“Resolving dependencies”阶段直接失败，报错类似：Your requirements could not be resolved to an installable set of packages.
必须检查的项：
- 运行
php -v，确认输出为PHP 8.2.x或更高 - 运行
php -m | grep -E 'mbstring|openssl|xml|curl|ctype|json'，6 个扩展缺一不可 - Docker 用户注意镜像标签：用
php:8.2-apache，别用php:8或php:latest - Mac Homebrew 用户检查
which php和composer --version是否指向同一版本（常见坑：终端调用的是系统自带 PHP 8.1）
国内网络下 Composer 镜像与安装卡顿排查
卡在 Loading composer repositories 或长时间停在 Installing dependencies，90% 是网络或权限问题，和 Laravel 本身无关。
实操建议：
- 临时切阿里云镜像：
composer create-project --repository=https://mirrors.aliyun.com/composer/ laravel/laravel my-app "^11.0@rc"，避免污染全局配置 - 验证 cURL 和 SSL：
php -r "print_r(openssl_get_cert_locations());"，看default_cert_file路径是否存在且可读（尤其 macOS M1/M2） - 排除权限干扰：换到
/tmp/test-laravel目录重试；Docker volume 挂载时确认 uid/gid 匹配，否则vendor/写入失败 - 加
-vvv参数重跑命令，观察最后卡在哪一行（比如卡在某个包的 zip 解压，说明是 zlib 或磁盘空间问题）
装完不能直接跑，三件事必须立刻做
即使 create-project 成功返回，项目也还没准备好运行。Laravel 11 移除了内置 serve 命令，且默认不生成密钥——这意味着你访问 http://localhost:8000 会看到 500 错误或空白页。
进入项目目录后，必须顺序执行：
-
php artisan key:generate：生成APP_KEY，否则所有加密/Session 功能失效 -
php artisan config:clear：清空旧缓存（尤其从旧项目复制过来时） -
php artisan serve已被移除，改用：php -S localhost:8000 -t public（PHP 内置服务器）或./sail up（Docker 方案）
storage 和 bootstrap/cache 目录的写权限常被忽略——特别是 Windows 或 Docker 场景下，chmod -R 775 storage bootstrap/cache 这类操作可能无效，需结合容器用户或 WSL 权限模型处理。
