macOS部署Laravel失败主因是环境链路未对齐：需验证PHP≥8.2且mbstring等扩展全启用、Composer≥3.x并配置阿里云镜像、执行.env生成、key:generate及storage权限设置三步缺一不可。
macOS 上部署 Laravel 失败，绝大多数不是框架问题，而是环境链路没对齐：PHP 版本和扩展没真正启用、Composer 镜像源卡住、项目初始化后关键步骤被跳过。下面直击 macOS 用户最常卡住的三个环节，每一步都带验证方法和操作命令。
PHP 8.2+ 必须真实启用全部必需扩展
Laravel 11 要求 PHP ≥ 8.2，Laravel 12/13 已要求 ≥ 8.3；但装了不等于能用——必须确认扩展在运行时加载成功。
- 运行 php -v，输出应为
PHP 8.3.x或PHP 8.4.x（Laravel 13.2 官方推荐 8.3+） - 运行 php -m | grep -E "(mbstring|openssl|pdo|tokenizer|xml|ctype|json|bcmath|fileinfo|zip|curl)"，每一项都必须有输出；缺任何一项都会导致 artisan 命令崩溃或路由不响应
- 若用 Homebrew 安装（推荐）：
brew install php@8.4→brew link php@8.4→ 把/opt/homebrew/bin（Apple Silicon）或/usr/local/bin（Intel）加入$PATH - 验证 php.ini 路径：
php --ini，打开显示的配置文件，检查extension=行是否全部取消注释（如extension=mbstring），改完需重启终端
Composer 3.x + 国内镜像必须生效
Composer 2.x 无法安装 Laravel 11+，且默认源在国内极慢，不配镜像几乎必卡在 “Resolving dependencies”。
- 运行 composer --version，输出必须是
3.x（如3.5.6），不是2.x - 全局配置阿里云镜像：
composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/ - 创建项目时锁定 LTS 版本（避免依赖过高 PHP）：
composer create-project laravel/laravel:^10.0 myapp --no-interaction --prefer-dist
或直接用 Laravel 13（需 PHP 8.3+）：composer create-project laravel/laravel myapp --no-interaction --prefer-dist - 若仍卡住，清 Composer 缓存：
rm -rf ~/.composer/cache，再加内存限制重试：COMPOSER_MEMORY_LIMIT=-1 composer create-project laravel/laravel myapp
.env 生成 + 权限 + 缓存三步缺一不可
页面空白、403、登录失败、数据库连不上，90% 是这三项漏做或顺序错乱。
- 进项目根目录，确认
.env存在：
若没有，运行cp .env.example .env - 立即生成密钥：
php artisan key:generate—— 缺这步，CSRF、Session、加密全失效 - 确保
storage和bootstrap/cache可写：chmod -R 775 storage bootstrap/cache（不建议 777，开发环境 775 足够） - 修改 .env 后必须清缓存：
php artisan config:clear→php artisan cache:clear→php artisan route:clear
否则所有配置变更（如 DB_HOST、APP_DEBUG）都不生效 - 启动服务：
php artisan serve（推荐，监听http://127.0.0.1:8000，自动处理路由）
不要用 file:// 打开 index.php，也不要用 MAMP/XAMPP 直接指向项目根目录——必须指向public/子目录
不复杂但容易忽略。
