Mac装Laravel最易卡在PHP扩展缺失、.env文件缺失、权限错误和Composer镜像慢四点，前两者占报错70%以上：需用php -m检查并启用mbstring/openssl/tokenizer/ctype扩展，复制.env.example生成.env后执行php artisan key:generate，配置国内镜像并修复~/.composer及项目目录权限。
Mac 上装 Laravel 最容易卡在 PHP 扩展缺失、.env 文件缺失、权限错误和 Composer 镜像慢这四点，其中前两点占实际报错的 70% 以上。
PHP 扩展不全导致 laravel new 直接失败
运行 laravel new my-project 时如果报 “The following PHP extensions are required but are not installed”，说明系统 PHP 缺少 Laravel 强制依赖的扩展。macOS 自带的 PHP（或 Homebrew 安装的）默认不启用全部扩展，尤其 mbstring、openssl、tokenizer、ctype 这几个最常漏。
- 用
php -m检查已加载模块，确认列表里有上述四个名称 - Homebrew PHP 用户：编辑
/usr/local/etc/php/8.x/php.ini（x 是你的版本号），取消注释或添加extension=mbstring.so等行 - 若用
pecl install mongodb类扩展，必须同时确保extension=mongodb.so写入 php.ini，且该 so 文件真实存在（ls /usr/local/lib/php/pecl/20220829/可查） - 改完 php.ini 后必须重启 PHP-FPM：
brew services restart php，否则php -m看不到新加的扩展
.env 文件不存在引发 key:generate 报错
从 Git 克隆项目或用 composer create-project 初始化后，根目录只有 .env.example，没有 .env。此时执行 php artisan key:generate 会报 file_get_contents(.../.env): failed to open stream —— 不是命令错了，是文件根本没创建。
- 别手动新建空
.env文件，直接复制：cp .env.example .env - macOS 下如果提示 Permission denied，不是一定要加
sudo，而是先确认当前用户对项目目录有写权限：ls -la看属主，必要时chown -R $USER:staff ./my-project - 复制后立刻执行
php artisan key:generate，它会自动往.env里写入APP_KEY行；如果APP_KEY已存在非空值，命令不会覆盖，得手动删掉再跑 -
.env必须是 UTF-8 无 BOM 格式，用 VS Code 或 Sublime 打开时留意右下角编码显示，避免因隐藏字符导致解析失败
Composer 权限与镜像问题拖慢安装过程
在 Mac 上执行 composer install 卡住、超时、或提示 “Permission denied” 写 vendor/，通常不是网络问题，而是本地配置或权限链断裂。
- 先检查 Composer 全局配置是否用了国内镜像：
composer config -g repo.packagist，如果不是https://mirrors.aliyun.com/composer/，立即设上 - 升级超时阈值：
composer config -g process-timeout 600，避免默认 300 秒中断 - 如果
vendor/目录报 Permission denied，不要直接sudo composer install，而应修复用户归属：sudo chown -R $USER:staff ~/.composer和chown -R $USER:staff ./my-project - 遇到 “Class 'Illuminate\Foundation\Application' not found”，大概率是
vendor/autoload.php没生成成功，删掉vendor/和composer.lock，重跑composer install
Homestead 虚拟机方案反而引入新路径陷阱
用 Homestead 的人常以为“不用管本机环境”，结果在共享目录里跑 php artisan serve，浏览器访问却 404 —— 因为 Homestead 的 Nginx 配置默认只认 /home/vagrant/code/ 下的站点，而你把项目放到了 ~/Sites/laravel-app 并做了软链，Nginx 实际没读到真实路径。
- 务必在
Homestead.yaml的folders:和sites:区块里显式声明路径，例如：- map: ~/Sites/laravel-app+to: /home/vagrant/code/laravel-app - 修改
Homestead.yaml后必须vagrant reload --provision，只vagrant reload不会重载 Nginx 配置 - Homestead 内默认 PHP 版本可能和宿主机不同，
vagrant ssh进去后先跑php -v，再确认which php，避免在错误的 PHP 环境下执行 Artisan 命令 - 如果用
php artisan serve，注意它绑定的是虚拟机内网地址（如127.0.0.1:8000），需在 Homestead.yaml 中加ports:映射，否则宿主机浏览器打不开
真正麻烦的从来不是“哪一步没做”，而是某一步做了但没生效——比如改了 php.ini 却忘了重启服务，或者复制了 .env.example 但编辑器悄悄加了不可见字符。验证动作是否落地，比记住步骤更重要。
