laravel 12 在 macos 上应弃用 laravel new，改用 composer create-project laravel/laravel myapp "12.*" 直接安装；必须使用 php ≥ 8.3（非 8.2 或 8.4-dev），并确保 mbstring、openssl、pdo、tokenizer、xml、ctype、json、zip 全部启用，安装后执行 cp .env.example .env 和 php artisan key:generate，再运行 php artisan serve 验证。
laravel new 在 macOS 上已不推荐，Laravel 12 要求 PHP ≥ 8.3，且官方默认不再维护全局 laravel/installer。最稳、最快的方式是直接用 composer create-project，跳过 installer 缓存和版本滞后问题。
确认 PHP 8.3+ 和必要扩展
Laravel 12 不兼容 PHP 8.2 或更低版本，缺一个扩展就会卡在 composer install 阶段：
-
php -v必须输出8.3.x（不是8.2或8.4-dev） -
php -m中必须包含：mbstring、openssl、pdo、tokenizer、xml、ctype、json、zip - Mac 用户用 Homebrew 安装后，常漏掉启动服务：
brew services start php@8.3 - 如果
php -m | grep mbstring无输出，运行：brew reinstall php@8.3（Homebrew 会自动启用全部扩展）
用 composer create-project 直接拉 Laravel 12
别碰 laravel new myapp——它底层仍调 create-project，但多一层 installer 版本判断，容易因网络或缓存拉到旧版（比如 11.x）：
- 执行：
composer create-project laravel/laravel myapp "12.*" - 加
"12.*"强制锁定主版本，避免 Composer 自作主张选11.42 - 加
--prefer-dist（默认已有）提速；如遇超时，先换国内镜像：composer config -g repo.packagist composer https://packagist.phpcomposer.com - 全程不要加
sudo——权限错误会导致vendor/写入失败，后续php artisan命令全报错
生成密钥 + 检查 .env 是硬性前置动作
项目目录生成完，cd myapp 后立刻做这两件事，否则 php artisan serve 必报错：
-
cp .env.example .env——.env文件不存在是常见疏漏，尤其从 Git 下载 zip 包时 -
php artisan key:generate——没这步会触发RuntimeException: No application encryption key has been specified，页面空白，日志里只显示 cipher 错误（误导性强） - 检查
.env中APP_KEY是否已写入（值应为base64:开头的 44 字符字符串） - 如果提示
file_get_contents(.../.env): failed to open stream，说明.env还没复制成功，重跑cp命令
启动前绕开 Valet / Herd 的干扰
Mac 用户容易下意识用 valet park 或 herd add，但 Laravel 12 开发初期没必要——它们引入 DNS、HTTPS、Nginx 层，反而掩盖真实环境问题：
- 先用原生命令验证是否跑通：
php artisan serve - 默认监听
http://127.0.0.1:8000；如端口被占，加--port=8080 - 看到欢迎页 ≠ 成功：打开 DevTools → Network，确认
/_debugbar/assets/stylesheets等资源能 200 加载（排除public/权限或重写问题） - 真要上 Valet/Herd，等
artisan serve跑通后再装，顺序错了，连key:generate都可能因路径解析失败而报错
真正卡住人的从来不是“怎么装”，而是 PHP 版本错位、.env 缺失、APP_KEY 没生成这三处——它们不出现在任何报错标题里，却让整个流程停在黑屏或 500 页面。每步做完，用 ls -la 看一眼 .env 和 storage/logs/laravel.log 最顶行，比反复重装快得多。
