重量级开发环境：Homestead

---

简介

Laravel 为开发者提供了一套完善的重量级本地开发环境 —— Laravel Homestead。

Laravel Homestead 实际是一个打包好各种 Laravel 开发所需软件和工具的 Vagrant 盒子（关于 Vagrant 盒子的释义请参考 Vagrant 官方文档），该盒子为我们提供了一个优秀的开发环境，有了它，我们不再需要在本地环境安装 PHP、Composer、Nginx、MySQL、Memcached、Redis、Node 等其它工具软件，我们也完全不用再担心误操作搞乱操作系统 —— 因为 Vagrant 盒子是一次性的，如果出现错误，可以在数分钟内销毁并重新创建该 Vagrant 盒子！

为什么说它是重量级的开发环境呢？谁用谁知道，要使用上这个开发环境，你需要安装 Vagrant、VirtualBox，下载 Homestead 对应的 Vagrant 盒子，经历一系列下载、安装和配置之后才能使用（可能需要花费数小时），如果是 Mac 或 Linux 系统可能还比较顺利，如果是 Windows 系统的话就得先烧柱香拜拜菩萨再开始，保佑一切顺利，哈哈，开玩笑啦，不过 Windows 确实相对而言出问题的概率比较大。

有人要说了，听上去这么复杂，我就不用了，不过相信我吧，这点时间都会在日后因为 Homestead 强大完善的功能在开发过程中补回来，正所谓磨刀不误砍柴功，Homestead 不仅为你提供了一整套日后开发所需要的工具，而且与 Laravel 配置文件默认配置无缝结合，省去了很多配置的麻烦，此外，如果是在团队中开发的话，Homestead 还为你们提供了一致的开发环境，避免因为不同开发人员使用的工具软件版本不同造成线上的问题，这三个理由，我想足够可以说服你了。

当然，如果你只是想简单尝鲜，不使用 Homestead 也无可厚非，毕竟 Mac 下有 Valet，Windows 下则可以使用 Xampp 之类的便捷工具包，但是如果是工程化开发，走正规军路子还是推荐使用 Homestead。

注：如果你使用的是 Windows，需要开启系统的硬件虚拟化（VT-x），这通常可以通过 BIOS 来开启。如果你是在 UEFI 系统上使用 Hyper-V，则需要关闭 Hyper-V 以便可以访问 VT-x。

预装软件

Homestead 可以运行在 Windows、Mac 以及 Linux 等主流操作系统上，预装的软件和工具列表如下：

• Ubuntu 18.04
• Git
• PHP 7.4
• PHP 7.3
• PHP 7.2
• PHP 7.1
• PHP 7.0
• PHP 5.6
• Nginx
• MySQL
• lmm（用于 MySQL 或 MariaDB 数据库快照）
• SQLite3
• PostgreSQL
• Composer
• Node（With Yarn, Bower, Grunt, and Gulp）
• Redis
• Memcached
• Beanstalkd
• Mailhog
• avahi
• ngrok
• Xdebug
• XHprof/Tideways/XHGui
• wp-cli

可选软件

此外，你还可以选择性安装以下软件：

• Apache
• Blackfire
• Cassandra
• Chronograf
• CouchDB
• Crystal & Lucky Framework
• Docker
• Elasticsearch
• Gearman
• Go
• Grafana
• InfluxDB
• MariaDB
• MinIO
• MongoDB
• MySQL 8
• Neo4j
• Oh My Zsh
• Open Resty
• PM2
• Python
• RabbitMQ
• Solr
• Webdriver & Laravel Dusk 相关工具

安装 & 设置

首次安装

在使用 Homestead 之前，需要先安装 Virtual Box、VMWare、Parallels 或 Hyper-V （四选一，我们通常选择 VirtualBox，因为只有它是免费的）以及 Vagrant，所有这些软件包都为常用操作系统提供了一个便于使用的可视化安装器，通过安装界面引导就可以完成安装。

注：直接下载安装相应软件的最新版本即可。

要使用 VMware 的话，需要购买 VMware Fusion（Mac） / Workstation（Windows） 以及 VMware Vagrant 插件，尽管不便宜，一套下来要 1000 多块人民币，但是 VMware 可以提供更好的性能和体验（废话，不然谁用，不过考虑到这个价格，只能呵呵了）。

要使用 Parallels 的话，需要安装 Parallels Vagrant 插件，这是免费的（仅仅是插件免费哈）。

由于 Vagrant 限制的因素，Hyper-V 提供者会忽略所有网络设置。

安装 Homestead Vagrant 盒子

VirtualBox/VMWare 和 Vagrant 安装好了之后，在终端中使用如下命令将 Homestead Vagrant 盒子 laravel/homesterad 添加到 Vagrant 中。下载该盒子将会花费一些时间，具体时间长短主要取决于你的网络连接速度（建议在有梯子的条件下下载）：

vagrant box add laravel/homestead

如果上述命令执行失败，需要确认 Vagrant 是否是最新版本，如果不是的话更新 Vagrant 到最新版本并升级所有插件。

运行命令会列出一个选择列表，选择 virtualbox 对应选项序号 2 即可，然后进入漫长的下载等待：

下载速度因人而异，如果一直提示网络超时的话只能去 Vagrant 官网下载最新版本了：https://vagrantcloud.com/laravel/boxes/homestead/versions/9.3.0/providers/virtualbox.box，你可以直接通过浏览器下载，也可以通过拷贝链接到迅雷等下载工具下载，比如学院君这里通过迅雷下载，以便借助加速通道提升加载速度：

显然比命令行的方式速度快多了。

通过后面这种方式下载完成后，需要手动将下载的盒子路径添加到 Vagrant：

vagrant box add laravel/homestead ~/Downloads/virtualbox.box

运行上述命令有可能报错：

Check your Homestead.yaml file, the path to your private key does not exist.

解决办法如下：

ssh-keygen -t rsa -b 4096 -C "your_email@example.com"
eval "$(ssh-agent -s)"
ssh-add -K ~/.ssh/id_rsa

再次运行上述命令即可添加成功：

安装 Homestead

你可以通过克隆仓库代码来实现 Homestead 安装。将仓库克隆到用户「家」目录下的 Homestead 目录（没有的话自己创建一个），这样 Homestead 盒子就可以作为所有 Laravel 项目的主机：

git clone https://github.com/laravel/homestead.git ~/Homestead

克隆完成后，你需要检查 Homestead 的版本标签，因为 master 分支不会总是稳定版本，你可以在 GitHub Release Page 查找到最新稳定版本，此外，你还可以检出 release 分支，因为它总是包含最新稳定版本：

cd ~/Homestead

git checkout release

接下来，在 Homestead 目录下运行 bash init.sh 命令来创建 Homestead.yaml 配置文件，生成的 Homestead.yaml 配置文件文件位于当前 Homestead 目录：

// Mac/Linux...
bash init.sh

// Windows...
init.bat

配置 Homestead

设置 Provider

Homestead.yaml 文件中的 provider 键表示使用哪个 Vagrant 提供者：virtualbox、vmware_fushion、 vmware_workstation、parallels 或 hyperv，你可以将其设置为自己选择的提供者，当然对大部分人来说也没得选：

provider: virtualbox

配置共享文件夹

Homestead.yaml 文件中的 folders 属性列出了所有主机和 Homestead 虚拟机共享的文件夹，一旦这些目录中的文件有了修改，将会在本地和 Homestead 虚拟机之间保持同步，如果有需要的话，你可以配置多个共享文件夹：

folders:
    - map: ~/code/project1
      to: /home/vagrant/project1

注：map 表示宿主机 Web 项目根目录，to 表示映射到的虚拟机 Web 项目根目录，Windows 下需要将 ~ 替换成完整的目录路径，比如 C:\Users\user\Code\project1。

你需要将每个项目映射自己的对应目录而不是映射整个 ~/code 目录：

folders:
    - map: ~/code/project1
      to: /home/vagrant/project1

    - map: ~/code/project2
      to: /home/vagrant/project2

当你映射目录时，虚拟机会跟踪该目录下每个文件的所有磁盘 IO，随着站点数量的增加，可能会遇到性能问题，尤其是在包含大量文件的低端机器或项目中，性能问题可能会非常明显，这是因为这个原因，所以不推荐映射整个 ~/code 目录。

注：在使用 Homestead 的时候，永远不要挂载当前目录（.），这会导致 Vagrant 不映射当前目录到 /vagrant 并且在 provision 过程中断可选功能，造成异常结果。

如果要开启 NFS，只需简单添加一个标识到同步文件夹配置：

folders:
    - map: ~/code/project1
      to: /home/vagrant/project1
      type: "nfs"

注：使用 NFS 的话，需要安装 vagrant-winnfsd 插件。该插件可用于在 Homestead 盒子中为文件和目录维护正确的用户/组权限。

你还可以通过 options 传递其他 Vagrant 支持的同步文件夹选项：

folders:
    - map: ~/code/project1
      to: /home/vagrant/project1
      type: "rsync"
      options:
          rsync__args: ["--verbose", "--archive", "--delete", "-zz"]
          rsync__exclude: ["node_modules"]

配置 Nginx 站点

对 Nginx 不熟？没关系！通过 sites 属性你可以方便地将“域名”映射到 Homestead 虚拟机的指定目录，Homestead.yaml 中默认已经配置了一个示例站点。和共享文件夹一样，你可以配置多个站点：

sites:
    - map: homestead.test
      to: /home/vagrant/project1/public

如果你是在 Homestead 盒子启动之后进行了上述修改，需要运行 vagrant reload --provision 更新虚拟机上的 Nginx 配置。

注：Homestead 脚本被设计为尽可能保证操作的幂等，不过，如果你在 provison 过程中还是出现问题，则需要通过 vagrant destroy && vagrant up 命令来销毁并重构虚拟机。

主机名解析

Homestead 通过 mDNS 发布主机名来自动解析主机。如果你在 Homestead.yaml 中设置了 hostname: homestead，则该主机会以 homestead.local 的形式生效（可以通过 homestead.local 这个主机名来访问对应的虚拟机）。MacOS、iOS 和 Linux 桌面系统默认提供了对 mDNS 的支持，Windows 则需要额外安装 Bonjour Print Services for Windows 使其生效。

自动主机名在每个项目独立安装的 Homestead 中工作最好，如果你在一个 Homestead 实例上托管了多个站点，可以在宿主机上将站点「域名」添加到 hosts 文件中做域名映射，hosts 文件会将针对 Homestead 站点的请求重定向到 Homestead 虚拟机。在 Mac 和 Linux 系统中，该文件位于 /etc/hosts，在 Windows 系统中，该文件位于 C:\Windows\System32\drivers\etc\hosts。我们以 homestead.test 域名映射为例，添加到 hosts 文件的记录如下所示：

192.168.10.10 homestead.test

确保 IP 地址和你的 Homestead.yaml 文件中的 ip 配置项一致，一旦你将域名添加到 hosts 文件，就可以在浏览器中通过该域名访问站点了：

http://homestead.test

注：在真正可以访问站点之前，还需要通过 Vagrant 启动 Homestead 虚拟机，下面我们就来启动这个盒子。

启动 Vagrant 盒子

配置好 Homestead.yaml 文件后，在 Homestead 目录下运行 vagrant up 命令，如果你是通过先下载 Homestead Vagrant 盒子再手动添加的方式安装的话，此时先不要执行这个命令，而是需要进入 ~/.vagrant.d/boxes/laravel-VAGRANTSLASH-homestead 目录（以 MacOS 为例，Windows 对应的路径应该是 C:/Users/User/.vagrant.d/boxes/laravel-VAGRANTSLASH-homestead，其中 User 对应你的用户名），添加一个 metadata_url 文件，并初始化文件内容如下（如果已有则忽略）：

https://vagrantcloud.com/laravel/homestead

接下来，将该目录下手动添加到 Vagrant 盒子目录 0 重命名此次安装盒子版本号 9.3.0，再回到 Homestead 目录运行 vagrant up 命令。Vagrant 将会启动虚拟机并自动配置共享文件夹以及 Nginx 站点，初次启动需要花费一点时间进行初始化：

启动成功之后，就可以在浏览器中通过 http://homestead.test 访问 Laravel 应用了（前提是宿主机 Web 根目录下已经部署相应的 Laravel 应用代码）：

要登录到该虚拟机，使用 vagrant ssh 命令：

关闭该虚拟机，可以使用 vagrant halt 命令；销毁该虚拟机，可以使用 vagrant destroy --force 命令。

为每个项目安装 Homestead

全局安装 Homestead 将会使每个项目共享同一个 Homestead 盒子，你还可以为每个项目单独安装 Homestead，这样就会在该项目下创建 Vagrantfile，允许其他人在该项目中执行 vagrant up 命令，在指定项目根目录下使用 Composer 执行安装命令如下：

composer require laravel/homestead --dev

这样就在项目中安装了 Homestead。Homestead 安装完成后，使用 make 命令生成 Vagrantfile 和 Homestead.yaml 文件，make 命令将会自动配置 Homestead.yaml 中的 sites 和 folders 属性。该命令执行方式如下：

Mac/Linux：

php vendor/bin/homestead make

Windows:

vendor\\bin\\homestead make

以我的项目 laravel7 为例，生成的 Homestead.yaml 配置文件如下：

ip: 192.168.10.10
memory: 2048
cpus: 2
provider: virtualbox
authorize: ~/.ssh/id_rsa.pub
keys:
    - ~/.ssh/id_rsa
folders:
    -
        map: ~/Docker/wwwroot/laravel7
        to: /home/vagrant/code
sites:
    -
        map: homestead.test
        to: /home/vagrant/code/public
databases:
    - homestead
features:
    -
        mariadb: false
    -
        ohmyzsh: false
    -
        webdriver: false
name: laravel7
hostname: laravel7

将其中的 sites 配置中 map 配置项修改为 laravel7.local。接下来，打开终端进入项目根目录运行 vagrant up 命令，然后在浏览器中通过 http://laravel7.local 访问站点。

可以看到我们并不需要在 hosts 中添加域名映射，这得益于基于 mDNS 的主机名自动解析机制，当然，你也可以沿袭共享 Homestead 那种域名解析机制，就是麻烦点，需要每次到 hosts 中添加域名映射。

安装可选软件

安装可选软件可以在 Homestead 配置文件 Homestead.yaml 中使用 features 设置来实现，大部分软件只需要通过布尔值设置启用或者禁用来选择安装或者不安装，小部分软件还允许配置多个选项：

features:
    - blackfire:
        server_id: "server_id"
        server_token: "server_value"
        client_id: "client_id"
        client_token: "client_value"
    - cassandra: true
    - chronograf: true
    - couchdb: true
    - crystal: true
    - docker: true
    - elasticsearch:
        version: 7
    - gearman: true
    - golang: true
    - grafana: true
    - influxdb: true
    - mariadb: true
    - minio: true
    - mongodb: true
    - mysql8: true
    - neo4j: true
    - ohmyzsh: true
    - openresty: true
    - pm2: true
    - python: true
    - rabbitmq: true
    - solr: true
    - webdriver: true

MariaDB

启用 MariaDB 将会移除 MySQL 并安装 MariaDB。MariaDB 是 MySQL 的替代品，完全兼容 MySQL，所以在应用数据库配置中你仍然可以使用 mysql 驱动。

MongoDB

默认安装的 MongoDB 将会设置数据库用户名为 homestead 及对应的密码为 secret。

Elasticsearch

安装 Elasticsearch 的时候需要指定一个支持的版本。默认安装会创建一个名为「homestead」的集群，不要给 Elasticsearch 分配超过操作系统一半的内存，因此确保 Homestead 机器内存至少是分配给 Elasticsearch 的两倍。

注：查看 Elasticsearch 文档学习如何自定义配置。

Neo4j

Neo4j 是一个图形数据库管理系统，默认安装的 Neo4j 会设置数据库用户名为 homestead 及对应的密码 secret。要查看 Neo4j，可以在浏览器中访问 http://homestead.test:7474，Neo4j 对外提供了三个端口：7687（Bolt）、7474（HTTP）、7473（HTTPS） 用于从客户端访问。

别名

你可以在 Homestead 目录下通过编辑 aliases 文件为 Homestead 机器添加 Bash 别名：

alias c='clear'
alias ..='cd ..'

更新完 aliases 文件后，需要通过 vagrant reload --provision 命令重启 Homestead 机器，以确保新的别名在机器上生效。

日常使用

全局访问 Homestead

要想在文件系统的任意路径都能够运行 vagrant up 启动 Homestead 虚拟机，在 Mac/Linux 系统中，可以添加 Bash 函数到 ~/.bash_profile；在 Windows 系统上，需要添加「批处理」文件到 PATH。这些脚本允许你在系统的任意位置运行 Vagrant 命令，并且把命令执行位置指向 Homestead 的安装路径。

Mac/Linux

function homestead() {
    ( cd ~/Homestead && vagrant $* )
}

确保将该函数中的 ~/Homestead 路径调整为指向实际的 Homestead 安装路径。这样你就可以在系统的任意位置运行 homestead up 或 homestead ssh 来启动/登录虚拟机：

补充知识点：/etc/profile 和 ~/.bash_profile 都可以用来设置系统 PATH，不同之处在于前者是给系统超级用户使用，后者是给普通登录用户使用的，此外要让 ~/.bash_profile 修改后生效，有两种方法，一种是退出系统重新登录，一种是使用 source ~/.bash_profile 命令。

Windows

在系统的任意位置创建一个批处理文件 homestead.bat：

@echo off

set cwd=%cd%
set homesteadVagrant=C:\Homestead

cd /d %homesteadVagrant% && vagrant %*
cd /d %cwd%

set cwd=
set homesteadVagrant=

你需要将脚本中实例路径 C:\Homestead 调整为 Homestead 实际安装路径。创建文件之后，添加文件路径到 PATH，这样你就可以在系统的任意位置运行 homestead up 或 homestead ssh 命令了。

通过 SSH 连接

你可以在 Homestead 目录下通过运行 vagrant ssh 以 SSH 方式连接到虚拟机。如果你设置了全部访问 Homestead，也可以在任意路径下通过 homestead ssh 登录到虚拟机。

如果你需要频繁登录到 Homestead 虚拟机，可以考虑将上述功能添加宿主机以便快速通过 SSH 进入 Homestead 盒子。

连接到数据库

Homestead 默认已经在虚拟机中为 MySQL 和 Postgres 数据库做好了配置，更方便的是，这些配置值与 Laravel 的 .env 中默认提供的配置一致。

想要通过本地的 Navicat 或 Sequel Pro 连接到 Homestead 上的 MySQL 或 Postgres 数据库，可以通过新建连接来实现，主机 IP 都是 127.0.0.1，对于 MySQL 而言，端口号是 33060，对 Postgres 而言，端口号是 54320，用户名/密码是 homestead/secret：

注：只有从本地连接 Homestead 的数据库时才能使用这些非标准的端口，在 Homestead 虚拟机中还是应该使用默认的 3306 和 5432 端口进行数据库连接配置。

数据库备份

当 Vagrant 盒子被销毁时，Homestead 可以自动备份数据库。要使用这个功能，必须使用 Vagrant 2.1.0 及以上版本，如果你在使用更低版本的 Vagrant，必须安装 vagrant-triggers 插件。要开启数据库自动备份，在 Homestead.yaml 文件中添加如下配置项：

backup: true

配置好了之后，Homestead 会在执行 vagrant destroy 命令时将数据库导出到 mysql_backup 和 postgres_backup 目录，这些目录可以在克隆 Homestead 代码的地方找到，如果你是用为单个应用安装的 Homestead，那么这些目录位于项目根目录下。

数据库快照

Homestead 支持保存 MySQL 和 MariaDB 数据库的状态并通过 Logical MySQL Manager在不同状态间进行切换。例如，假设你的站点数据库有几个 G 的数据量，你可以导入这个数据库并保存一份快照，在本地工作一段时间后有可能会创建一些新的测试内容，你可以通过快照快速恢复到最初的状态。

在底层，LMM 使用了 LVM 的支持写时复制的瘦快照功能，这意味着当修改表中某条记录时，只会将你所做的更改写入磁盘，从而在恢复期节省大量时间和磁盘空间。

由于 LMM 会与 LVM 进行交互，所以必须以 root 身份运行，要了解 LMM 支持的所有命令，可以在 Homestead 虚拟机中通过 sudo lmm 查看。lmm 常见的工作流会是这样：

1. 导入数据库到 lmm 默认的 master 分支；
2. 运行 sudo lmm branch prod-YYYY-MM-DD 保存尚未做任何修改的数据库快照；
3. 修改数据库记录；
4. 运行 sudo lmm merge prod-YYYY-MM-D 撤销所有修改；
5. 运行 sudo lmm delete <branch> 删除不需要的分支。

添加更多站点

Homestead 虚拟机在运行时，可能需要添加多个 Laravel 应用到 Nginx 站点。如果是在单个 Homestead 环境中运行多个 Laravel 应用，添加站点很简单，只需将站点添加到 Homestead.yaml 文件：

sites:
    - map: homestead.test
      to: /home/vagrant/project1/public
    - map: another.test
      to: /home/vagrant/project2/public

如果 Vagrant 不是自动管理「hosts」文件，需要添加站点域名到本地 hosts 文件：

192.168.10.10  homestead.test
192.168.10.10  another.test

添加完站点后，在 Homestead 目录下运行 vagrant reload --provision 命令重启虚拟机。

站点类型

Homestead 支持多种类型站点，所以即使你没有使用 Laravel 的话，也可以使用 Homestead，例如，我们可以通过 symfony2 站点类型轻松添加一个 Symfony 应用：

sites:
    - map: symfony2.test
      to: /home/vagrant/my-symfony-project/web
      type: "symfony2"

目前支持的站点类型包括 apache、apigility、expressive、laravel（默认）、proxy、silverstripe、statamic、symfony2、symfony4 和 zf。

站点参数

你也可以通过站点指令 params 添加额外的 Nginx fastcgi_param 值。例如，我们可以添加一个 FOO 参数，对应参数值是 BAR：

sites:
    - map: homestead.test
      to: /home/vagrant/project1/public
      params:
          - key: FOO
            value: BAR

环境变量

你可以通过将变量添加到 Homestead.yaml 文件来设置全局环境变量：

variables:
    - key: APP_ENV
      value: local
    - key: FOO
      value: bar

更新完 Homestead.yaml 文件后，需要通过 vagrant reload --provision 命令重启机器，这将会更新所有已安装版本 PHP 的 PHP-FPM 配置并且为 vagrant 用户更新环境。

配置 Cron 调度任务

Laravel 提供了很方便的方式来调度 Cron 任务：只需每分钟调度运行一次 Artisan 命令 schedule:run 即可。schedule:run 会检查定义在 App\Console\Kernel 类中定义的调度任务并判断运行哪些任务。

如果想要为某个 Homestead 站点运行 schedule:run 命令，需要在定义站点时设置 schedule 为 true：

sites:
    - map: homestead.test
      to: /home/vagrant/project1/public
      schedule: true

该站点的 Cron 任务会被定义在虚拟机的 /etc/cron.d 目录下。

配置 Mailhog

通过 Mailhog 可以轻松拦截发送出去的邮件并进行检查而不必真的将其发送给接收人。开始之前，需要更新 .env 文件使用如下邮件配置：

MAIL_DRIVER=smtp
MAIL_HOST=localhost
MAIL_PORT=1025
MAIL_USERNAME=null
MAIL_PASSWORD=null
MAIL_ENCRYPTION=null

配置好 Mailhog 后，你可以通过 http://localhost:8025 访问 Mailhog 后台管理页面。

配置 Minio

Minio 是一个开源的对象存储服务器，并且提供了与 Amazon S3 兼容的 API，要安装 Minio，需要更新 Homestead.yaml，在 features 配置项中启用它：

minio: true

默认情况下，Minio 可以通过 9600 端口访问，在浏览器中访问 http://homestead:9600/ 即可查看 Monio 控制面板，默认的 access key 是 homestead，默认的 secret key 是 secretkey，访问 Minio 时，需要使用 us-east-1 区域。

为了使用 Minio，你需要在配置文件 config/filesystems.php 中调整 S3 磁盘配置，添加 use_path_style_endpoint 配置项到 s3 配置项，并将 url 键修改为 endpoint：

's3' => [
    'driver' => 's3',
    'key' => env('AWS_ACCESS_KEY_ID'),
    'secret' => env('AWS_SECRET_ACCESS_KEY'),
    'region' => env('AWS_DEFAULT_REGION'),
    'bucket' => env('AWS_BUCKET'),
    'endpoint' => env('AWS_URL'),
    'use_path_style_endpoint' => true
]

最后，确保在 .env 文件中存在如下配置：

AWS_ACCESS_KEY_ID=homestead
AWS_SECRET_ACCESS_KEY=secretkey
AWS_DEFAULT_REGION=us-east-1
AWS_URL=http://homestead:9600

要配置 buckets，可以添加 buckets 指令到 Homestead 配置文件：

buckets:
    - name: your-bucket
      policy: public
    - name: your-private-bucket
      policy: none

目前支持的 policy 值包括：none、download、upload 和 public。

端口转发配置

默认情况下，Homestead 端口转发配置如下：

• SSH: 2222 → 转发到 22
• ngrok UI: 4040 → 转发到 4040
• HTTP: 8000 → 转发到 80
• HTTPS: 44300 → 转发到 443
• MySQL: 33060 → 转发到 3306
• Postgres: 54320 → 转发到 5432
• MongoDB: 27017 → 转发到 27017
• Mailhog: 8025 → 转发到 8025
• Minio: 9600 → 转发到 9600

其中前面表示宿主机端口，后面表示虚拟机端口。

转发更多端口

如果你想要为 Vagrant 盒子添加更多端口转发，做如下转发协议设置即可：

ports:
    - send: 50000
      to: 5000
    - send: 7777
      to: 777
      protocol: udp

共享你的环境

有时候，你可能希望和同事或客户共享自己当前的工作进度或成果，Vagrant 本身支持通过 vagrant share 来支持这个功能；不过，如果你在 Homestead.yaml 文件中配置了多个站点的话就不行了。

为了解决这个问题，Homestead 内置了自己的 share 命令，该功能实现的原理是通过 Ngrok将本地服务分享到互联网上进行公开访问，关于该软件的细节我们这里不讨论，大家可以自行搜索，我们主要关注在 Homestead 中如何使用这一功能。首先通过 vagrant ssh 登录到 Homestead 虚拟机然后运行 share homestead.test 命令，这样就可以分享 homestead.test 站点了，其他站点分享以此类推：

share homestead.test

运行完该命令之后，你就可以看到一个 Ngrok 界面出现，其中包含活动日志和分享站点所需的公开访问 URL：

可以看到我的共享 URL 是 http://c1676313.ngrok.io 以及 https://c1676313.ngrok.io，你可以通过这两个域名在任意联网机器上访问我的 Homestead 站点：

如果你想要指定一个自定义的区域，子域名或者其他 Ngrok 运行时选项，可以将它们添加到 share 命令：

share homestead.test -region=eu -subdomain=laravel

目前自定义域名只有付费用户才可以使用，所以 subdomain 会提示不可用。

注：记住两个点，一个是 Vagrant 并没有什么特别的安全防范措施，另一个是当你运行 share 命令的时候，你其实是在将自己的虚拟机曝光到互联网上。所以，当你要分享自己的站点之前，先想想安全隐患，并将其规避掉。

多个 PHP 版本

Homestead 6 引入了在单个虚拟机中支持多个 PHP 版本的功能，你可以在 Homestead.yaml 文件中为特定站点指定 PHP 版本，目前支持的 PHP 版本包括 5.6、7.0、7.1、7.2、7.3 和 7.4（默认版本）：

sites:
    - map: homestead.test
      to: /home/vagrant/project1/public
      php: "7.1"

该功能实现的原理是通过 Homestead.yaml 中配置的 PHP 版本在 Homestead 中启动相应的 php-fpm 服务，然后更新 Nginx 中相应的站点配置：

此外，你可以在 CLI 中使用任意版本的 PHP：

php5.6 artisan list
php7.0 artisan list
php7.1 artisan list
php7.2 artisan list
php7.3 artisan list
php7.4 artisan list

还可以在虚拟机中通过如下这些命令来更新默认的 CLI 版本：

php56
php70
php71
php72
php73
php74

非常方便：

Web 服务器

Homestead 使用 Nginx 作为默认 Web 服务器。不过，如果指定 apache 作为站点类型，也会安装 Apache。两个 Web 服务器可以同时安装，但是不能同时运行。Shell 命令 flip 可用于简化在不同 Web 服务器之间的切换处理，其工作原理是先自动判断哪个 Web 服务器正在运行，然后将其关闭，接着启动另一个服务器。要使用这个命令，需要通过 SSH 登录到 Homestead 虚拟机并在终端中运行：

flip

邮件

Homestead 内置了 Postfix 邮件转发代理，默认监听 1025 端口，所以，你可以指定应用使用 smtp 邮件驱动服务器为 localhost，端口号为 1025。这样，所有本地应用发送的邮件都会经由 Postfix 处理然后被 Mailhog 捕获。要查看所有发送到邮件，可以在浏览器访问 http://localhost:8025/。

调试 & 分析

通过 Xdebug 调试 Web 请求

Homestead 引入了 Xdebug 提供对逐步调试的支持。例如，你可以从浏览器加载某个页面，此时 PHP 会连接到你的 IDE 以便允许对运行代码进行检查和修改。

默认情况下，Xdebug 已经运行并且准备好接收连接，如果你需要在 CLI 中启用 Xdebug，在 Homestead 虚拟机中运行 sudo phpenmod xdebug 命令即可。接下来，按照 IDE 的引导来启用调试功能。最后，通过浏览器扩展或者 bookmarklet 配置浏览器触发 Xdebug。

注：Xdebug 会导致 PHP 运行变慢，要禁用 Xdebug，可以在虚拟机中运行 sudo phpdismod xdebug 并重启 PHP-FPM 服务。

调试 CLI 应用

要调试 PHP CLI 应用（命令行），可以在虚拟机中使用 shell 别名 xphp 命令：

xphp path/to/script

自动启动 Xdebug

当发送请求到 Web 服务器调试功能测试时，自动启动调试比修改测试通过自定义请求头或者 Cookie 来触发调试要轻松许多。要设置 Xdebug 自动启动，可以在虚拟机中编辑 /etc/php/7.#/fpm/conf.d/20-xdebug.ini 添加如下配置来完成：

; If Homestead.yml contains a different subnet for the IP address, this address may be different...
xdebug.remote_host = 192.168.10.1
xdebug.remote_autostart = 1

使用 Blackfire 分析应用

Blackfire 是一个用于分析 Web 请求和 CLI 应用以及编写性能断言的 Saas 服务，它提供了一个交互式用户界面用来显示调用关系图和时间线中的分析数据，可以在开发、预发和生产环境中使用，对终端用户来说也没有额外开销，我们可以通过它实现代码和 php.ini 配置的性能、质量和安全检查。

Blackfire Player 是一个开源的功能强大的 Web 爬取、测试和数据提取应用，可以和 Blackfire 一起用于脚本分析场景。

要启用 Blackfire，使用 Homestead 配置文件的 features 配置项来设置即可：

features:
    - blackfire:
        server_id: "server_id"
        server_token: "server_value"
        client_id: "client_id"
        client_token: "client_value"

Blackfire 服务器凭证和客户端凭证需要用户去 Blackfire 注册账号获取，Blackfire 提供了多个方案来分析应用，包括一个客户端工具和浏览器扩展，更多详细请参考 Blackfire 官方文档。

使用 XHGui 分析 PHP 性能

XHGui 是一个用于探索 PHP 应用性能的图形化界面，需要结合 XHProf 使用。要启用 XHGui，在站点配置中新增 xhgui: 'true' 配置即可：

sites:
    -
        map: your-site.test
        to: /home/vagrant/your-site/public
        type: "apache"
        xhgui: 'true'

如果站点已经存在，更新之后需要运行 vagrant provision 让其生效。

要分析一个 Web 请求，需要添加 xhgui=on 到查询字符串作为请求参数，XHGui 会自动添加 Cookie 到响应，以便后续请求不再需要添加查询字符串。你可以访问 http://your-site.test/xhgui 来查看应用分析结果。

要使用 XHGui 分析一个 CLI 请求，需要在命令之前加上 XHGUI=on 前缀：

XHGUI=on path/to/script

CLI 分析结果可以通过和 Web 分析结果一样的方式查看。

注意以上分析行为会让脚本执行变慢，甚至会导致性能降低一半，因此，我们通常会按照百分比选取一小部分样本进行分析，并根据分析结果进行改进，此外，注意分析结果中的执行时间包含了调试器中花费的所有时间。

由于性能分析会耗费大量的磁盘空间，它们会在几天之后被自动删除。

网络接口

Homestead.yaml 的 networks 属性用于配置 Homestead 的网络接口，你可以想配多少就配多少：

networks:
    - type: "private_network"
      ip: "192.168.10.20"

要开启 bridged （桥接模式）接口，需要配置 bridge 设置并修改网络类型为 public_network ：

networks:
    - type: "public_network"
      ip: "192.168.10.20"
      bridge: "en1: Wi-Fi (AirPort)"

要开启DHCP（动态主机配置协议），只需要从配置中移除 ip 选项即可：

networks:
    - type: "public_network"
      bridge: "en1: Wi-Fi (AirPort)"

扩展 Homestead

你可以使用 Homestead 根目录下的 after.sh 脚本来扩展 Homestead 的功能，在这个文件中，你可以添加任意 shell 命令来配置和自定义你的虚拟机。

自定义 Homestead 时，Ubuntu 可能会问你想要保持包的原生配置还是通过一个新的配置文件来覆盖它。如果要避开这个选择，需要在安装软件包时使用如下命令来避免覆盖由 Homestead 写入的任何配置：

sudo apt-get -y \
    -o Dpkg::Options::="--force-confdef" \
    -o Dpkg::Options::="--force-confold" \
    install your-package

用户自定义

在团队环境中使用 Homestead 时，你可能想要调整 Homestead 以便更好地适应你自己喜好的个人开发风格，这可以通过在 Homestead 根目录下创建 user-customizations.sh 文件来完成，在这个文件中，你可以做一些自己喜欢的定制化工作，不过，不要把这个文件提交到代码仓库中就好。

更新 Homestead

更新 Homestead 之前确保你已经在 Homestead 目录下通过如下命令移除了当前的虚拟机：

vagrant destroy

接下来，需要更新 Homestead 源码，如果你已经克隆仓库到本地，可以在项目根目录下运行如下命令进行更新：

git fetch

git pull origin release

这些命令会从 Github 拉取最新的 Homestead 仓库代码到本地，包括最新的标签，然后检出最新的标签版本（比如 v10.4.0）。你可以在 Github 版本发布页面查看最新的稳定版本号。

如果你是通过 Composer 在指定 Laravel 项目中安装的 Homestead，需要确保 composer.json 中包含了 "laravel/homestead": "^10" 然后更新这个依赖：

composer update

然后，需要通过 vagrant box update 命令更新 Vagrant 盒子：

vagrant box update

最后，你需要重新生成新的 Homestead 盒子来使用最新安装的 Vagrant：

vagrant up

虚拟机指定设置

VirtualBox

natdnshostresolver

默认情况下，Homestead 配置项 natdnshostresolver 被设置为 on，从而允许 Homestead 使用主机操作系统的 DNS 配置，如果你想要覆盖这个行为，添加如下行到 Homestead.yaml 文件：

provider: virtualbox
natdnshostresolver: 'off'

Windows 上的符号链接

如果符号链接在 Windows 机器上不能正常工作，可能需要添加如下区块到 Vagrantfile：

config.vm.provider "virtualbox" do |v|
    v.customize ["setextradata", :id, "VBoxInternal2/SharedFoldersEnableSymlinksCreate/v-root", "1"]
end

实例教程

• 基于 Laravel 开发博客应用系列 —— 设置 Windows 本地开发环境
• 基于 Laravel 开发博客应用系列 —— 设置 Linux/Mac 本地开发环境
• 基于 Laravel 开发博客应用系列 —— Homestead 和 Laravel 安装器
• 在 Laravel Homestead 中使用 Blackfire Profiler 对应用性能进行分析
• 基于 Laravel + Swoole + Vue 搭建实时在线聊天室（五）：Homestead 开发环境初始化