Homestead 是预装 PHP/MySQL/Nginx/Redis 的 Ubuntu 虚拟机环境，非直接安装 Laravel 的工具；Laravel 需在虚拟机内用 composer create-project 单独安装。
Homestead 不是“安装 Laravel 环境”的工具，而是提供一个**预装好完整 PHP/MySQL/Nginx/Redis 等服务的 Ubuntu 虚拟机环境**；Laravel 本身仍需在虚拟机内用 composer create-project 单独安装。跳过这层理解，直接照搬“一键装 Laravel”教程，90% 会卡在 vagrant up 失败、homestead.test 打不开、或本地代码不生效上。
Homestead 安装前必须确认的三件事
很多人失败不是命令输错了，而是基础依赖没对齐：
-
VirtualBox和Vagrant都必须已安装且版本兼容（2026 年推荐VirtualBox 7.0++Vagrant 2.4.0+；旧版如 VBox 6.1 与新版 Vagrant 可能触发 kernel panic） - Windows 用户必须关闭 Hyper-V 和 WSL2 冲突项：运行
cmd（管理员），执行bcdedit /set hypervisorlaunchtype off后重启 -
homestead.box不再默认远程下载——官方已将 box 移至 GitHub Releases，需手动下载对应版本（如laravel/homesteadv14.0.0 对应ubuntu-22.04），否则vagrant box add会超时或拉到废弃镜像
克隆 Homestead 仓库后必须改的两个配置点
bash init.sh 生成的 Homestead.yaml 是模板，不改就跑不起来：
-
ip字段不能和宿主机网段冲突（例如宿主机是192.168.1.100，就别设192.168.1.10；推荐统一用192.168.10.10） -
folders中的map必须是**绝对路径且不含中文/空格**（Windows 下写成C:/Users/John/code，不是C:\Users\John\code；macOS/Linux 用~/code即可） - 如果使用 SSH 密钥登录，
authorize和keys路径要真实存在；若跳过密钥，删掉这两行，否则vagrant up会 hang 在 “Waiting for SSH”
启动后 homestead.test 打不开的常见原因
域名解析、Nginx 配置、目录权限三者任一出错都会白屏或 403：
- hosts 文件必须加这一行：
192.168.10.10 homestead.test（注意是宿主机的hosts，不是虚拟机里的） -
sites配置里to:的路径必须精确到public子目录，比如/home/vagrant/code/myapp/public；少写/public就是 403 - 项目目录在宿主机创建后，需确保虚拟机里该路径有读取权限：
vagrant ssh进去后执行ls -l /home/vagrant/code/myapp，若显示Permission denied，说明共享挂载失败，回查folders.map路径是否拼错或权限受限
在 Homestead 里正确安装 Laravel 项目的唯一可靠方式
不要在宿主机用 composer create-project 生成 Laravel，再指望同步进虚拟机——vendor 目录权限和扩展名大小写会导致各种诡异报错：
- 先
vagrant ssh进虚拟机，cd 到映射目录下（如/home/vagrant/code） - 执行
composer create-project --prefer-dist laravel/laravel myapp（--prefer-dist避免 Git 克隆慢） - 确保
myapp目录属主是vagrant:vagrant：sudo chown -R vagrant:vagrant myapp - 若提示
Mcrypt或ext-pdo缺失，说明 PHP 版本不匹配——Homestead 默认启用 PHP 8.2，但某些老 Laravel 版本需切 PHP 7.4：sudo update-alternatives --config php
最容易被忽略的是：Homestead 启动后，所有 PHP/MySQL 服务都在虚拟机内运行，php artisan serve 不起作用，也无需它；访问必须走 Nginx + 域名，而不是 localhost:8000。任何试图绕过 sites 配置、直接用 PHP 内置服务器调试的行为，都会脱离 Homestead 的真实环境约束。
