应使用 composer create-project laravel/laravel my-app 安装 Laravel，它自动拉取骨架、安装依赖、生成 .env 并执行 key:generate；手动 init 再 require 会遗漏 autoload 配置、脚本钩子和环境初始化逻辑，导致 artisan 命令失效或 500 错误。
直接用 composer create-project laravel/laravel my-app，别手建再加依赖——后者大概率导致 artisan 找不到命令、vendor/autoload.php 加载失败、密钥没生成、.env 漏配置，全是隐形坑。
为什么不能先 composer init 再 require laravel/framework
因为 Laravel 不是单个库，而是一整套带脚本钩子（如 @php artisan package:discover）、自动加载规则（autoload 配置含 psr-4 + classmap）、环境初始化逻辑（.env 模板 + key:generate）的骨架项目。create-project 会完整复现这一流程；手动 init + require 只拉了核心框架，漏掉所有 glue logic。
-
artisan命令执行报错 “Command not found” 或 “Class not found”，往往是vendor/autoload.php没被正确引入，根源是 autoload 配置缺失或路径错乱 - 运行
php artisan serve后页面空白或报 500，常见原因是APP_KEY为空，而create-project默认会跑key:generate，手动方式不会 -
config/app.php中的providers数组依赖package:discover自动发现，没这步就等于“装了引擎但没点火”
create-project 指定版本时怎么写才不报错
版本号必须用语义化约束格式，且**不能带 v 前缀**。Composer 解析的是版本约束，不是 Git tag 名。
- ✅ 正确：
composer create-project laravel/laravel my-app "11.*"、"^11.0"、"11.42.0" - ❌ 错误：
composer create-project laravel/laravel my-app 11（会被当包名搜）、"v11.*"（解析失败）、"11.x"（非标准约束） - 验证方法：执行后进项目目录，看
composer.json里"laravel/framework"的 version 是否匹配预期（比如"^11.0"）
安装卡在 “Loading composer repositories” 或 “Installing dependencies” 怎么排查
这不是 Laravel 的问题，90% 是 Composer 环境或网络策略干扰，重点查三件事：
- 是否用了国内镜像源？没切的话，执行
composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/ - PHP 的 OpenSSL 扩展是否可用？运行
php -r "print_r(openssl_get_cert_locations());"，确认default_cert_file路径存在且可读（尤其 macOS M1/M2 + Homebrew PHP 容易 SSL 证书过期） - 目标目录权限是否允许写入？比如 Docker volume 挂载时 uid/gid 不匹配，会导致
vendor/创建失败，进程假死；可临时换到/tmp/test目录重试验证 - 加
-vvv参数重跑命令（如composer create-project -vvv laravel/laravel my-app "11.*"），看最后输出停在哪一行，精准定位卡点
最常被忽略的是：即使你指定了版本约束，如果本地 Composer 缓存了旧版元数据，也可能拉错依赖树——遇到诡异行为，先清缓存：composer clear-cache，再重试。
