Laravel9在Mac怎么使用Homestead-php教程-PHP中文网

homestead 在 mac 上运行 laravel 9 完全可行，但必须使用 v14.0.0 box（ubuntu 22.04 + php 8.2），并在 homestead.yaml 中显式配置 php: "8.2"，否则 enum 等特性将触发 fatal error。

laravel9在mac怎么使用homestead

Homestead 在 Mac 上跑 Laravel 9 是完全可行的，但默认的 Homestead Box（截至 2026 年主流仍基于 Ubuntu 20.04 / PHP 8.1）不原生支持 Laravel 9 所需的最低 PHP 版本（PHP 8.0+）——这本身不是问题，但容易踩坑：很多人直接拉最新 laravel/homestead box，却没注意它预装的是 PHP 8.1，而 Laravel 9 的某些组件（如 spatie/laravel-ignition、laravel/pint）在 PHP 8.1 下运行正常，但一旦你升级到 Laravel 9.51+ 或启用 php8.2 特性（如只读类、枚举匹配增强），就会报错或行为异常。

关键结论：别用默认 box 直接硬上，必须确认 PHP 版本并手动切到 8.2+。

确认 Homestead Box 是否内置 PHP 8.2+

当前（2026 年）官方维护的 laravel/homestead box 最新稳定版是 v14.0.0（对应 Ubuntu 22.04），它默认安装 PHP 8.2 —— 这才是 Laravel 9 安全运行的基线。执行以下命令验证：

vagrant box list | grep laravel/homestead

如果输出类似 laravel/homestead (virtualbox, 13.4.0)，说明你还在旧版（Ubuntu 20.04 + PHP 8.1）。必须升级：

先移除旧 box：vagrant box remove laravel/homestead --provider virtualbox
再拉新版：vagrant box add laravel/homestead --version 14.0.0
克隆最新 Homestead 配置脚本：git clone https://github.com/laravel/homestead.git ~/Homestead && cd ~/Homestead && git checkout v14.0.0

Homestead.yaml 中必须显式指定 PHP 版本

即使 box 是 14.0.0，vagrant up 启动时仍可能 fallback 到系统默认 PHP（尤其你本地 Mac 装过 brew php）。Laravel 9 项目必须由虚拟机内 PHP 8.2 解释执行，否则 php artisan 命令会失败或缓存错乱。

打开 ~/Homestead/Homestead.yaml，在 sites 下每个站点配置里加 php 字段：

sites:
  - map: myapp.test
    to: /home/vagrant/code/myapp/public
    php: "8.2"

注意：php: "8.2" 必须是字符串（带引号），YAML 解析器对数字类型不敏感；不写这行，Nginx 默认用 php8.1-fpm，Laravel 9 的 enum 类型反射会直接 fatal error。

Laravel Creem Agent

Creem 支付商店助理 — 查询订阅、客户、交易、产品，执行心跳检查，管理本地 Laravel支付商店。

下载

启动前必须关闭 macOS 自带的 Apache/PHP 冲突端口

Mac 系统自带 Apache 占用 80 端口，而 Homestead 默认也监听 80（通过 Nginx）。如果你没关，vagrant up 表面成功，但访问 myapp.test 会 502 或直接跳转到 macOS 默认页。

检查并停用：

sudo apachectl stop
sudo launchctl unload -w /System/Library/LaunchDaemons/org.apache.httpd.plist 2>/dev/null
顺手确认：lsof -i :80 应无 httpd 进程

另外，/etc/hosts 必须加这一行（不能只靠 homestead up 自动注入）：

192.168.10.10 myapp.test

首次 `vagrant up` 后必须进虚拟机验证 Laravel 9 运行环境

很多问题表面是“页面打不开”，实际是 composer install 没在虚拟机里跑，或 .env 文件权限不对。务必 SSH 进去手动走一遍：

vagrant ssh
cd code/myapp
php -v  # 确认输出包含 "8.2"
php artisan key:generate
php artisan config:clear
php artisan serve --host=0.0.0.0:8000  # 临时起服务测 CLI 是否正常

如果 php artisan 报 Class "Spatie\Ignition\IgnitionServiceProvider" not found，说明 composer install 是在 Mac 本地跑的（生成了 macOS 特有的 vendor/autoload.php），必须删掉 vendor 和 composer.lock，然后在 vagrant ssh 里重新 composer install。

真正的麻烦点不在安装步骤，而在「你以为配好了，其实 PHP 版本、Composer 执行环境、文件挂载权限、Nginx 的 PHP-FPM socket 路径」这四者只要一个不一致，Laravel 9 就会静默失败——尤其是 php artisan tinker 闪退或 Storage::put 权限拒绝这类问题，几乎都源于共享目录挂载时没加 type: "nfs" 或没设 mount_options。这些细节不进虚拟机看日志根本发现不了。