应使用 composer create-project laravel/laravel my-app 安装 Laravel，它自动拉取骨架、安装依赖、生成 .env 并执行 key:generate；指定版本需用 "10.*" 等语义化约束，不可省略引号或写 v 前缀。
直接用 create-project 装 Laravel，别手建项目再 composer require
Composer 官方推荐的 Laravel 安装方式是 create-project，不是先 composer init 再手动加依赖。后者容易漏掉 autoload 配置、脚本钩子（如 @php artisan package:discover），还会让 vendor/autoload.php 加载路径错乱，导致 artisan 找不到命令或类。
正确做法就是一条命令：
composer create-project laravel/laravel my-app
它会自动：拉取最新稳定版 Laravel 骨架、执行 composer install、生成 .env、运行 php artisan key:generate。省掉你手动补环境变量、密钥、权限设置这些易错环节。
指定 Laravel 版本时，版本号必须带 v 前缀或符合约束语法
想装 Laravel 10.x 而不是最新版？不能写 composer create-project laravel/laravel my-app 10 —— 这会报 Could not find package laravel/laravel with version 10。Composer 把 10 当作包名的一部分去搜了。
必须用标准版本约束写法：
composer create-project laravel/laravel my-app "10.*"composer create-project laravel/laravel my-app "10.42.0"composer create-project laravel/laravel my-app "^10.0"
注意：Laravel 的稳定发布版 tag 都带 v（比如 v10.42.0），但 Composer 版本约束里 不能写 v10.*，否则解析失败。它只认语义化版本格式，v 是 Git tag 标记，不是版本号本身。
安装卡在 “Loading composer repositories” 或 “Installing dependencies”
这通常不是 Laravel 的问题，而是 Composer 源或网络策略导致的。国内常见原因有三个：
- 没切阿里云/腾讯云镜像源：
composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/ - PHP cURL 扩展未启用，或 SSL 证书过期（尤其 macOS M1/M2 + Homebrew PHP）：运行
php -r "print_r(openssl_get_cert_locations());"看default_cert_file路径是否存在、是否可读 - 项目目录权限太严（比如挂载进 Docker 的 volume 设置了 uid/gid 不匹配），导致
vendor/写入失败，表现就是进程假死在 “Installing dependencies”
验证方法：加 -vvv 参数重试，看最后卡在哪一行；或者临时换到一个干净的 /tmp/test-laravel 目录试试，排除路径权限干扰。
装完发现 artisan 命令报错 Class 'Illuminate\Support\Facades\Storage' not found
这不是 Laravel 漏装，而是 composer install 没跑完 autoload 映射。常见于你手动删过 vendor/ 或 composer.lock 后又只跑了 composer update —— 它不会重建 vendor/autoload.php 中的 classmap 和 psr-4 映射。
解决只需一步：
composer dump-autoload
如果还报错，再补一句：
composer install --no-dev
注意：不要用 composer update 初始化新项目。它会强行升级所有依赖到最新兼容版，可能引入不兼容变更（比如升级了 doctrine/dbal 到 4.x 导致迁移失败），而 install 严格按 composer.lock 还原，才是初始化该做的事。
真正麻烦的是环境变量和权限混在一起出问题：比如 .env 里 APP_KEY 是空的，artisan 却试图加载加密服务；或者 storage/ 目录不可写但错误被静默吞掉。这种时候日志不报错，但页面白屏或 API 返回 500 —— 得翻 storage/logs/laravel.log 才能看到真实线索。
