Laravel 8 中文文档 Homestead

• 介绍
• 安装与设置
  • 第一步
  • 配置 Homestead
  • 启动 Vagrant Box
  • 为项目单独安装
  • 安装可选功能
  • 别名
• 日常使用方法
  • 全局访问 Homestead
  • 通过 SSH 连接
  • 连接数据库
  • 数据库备份
  • 数据库快照
  • 添加其他站点
  • 环境变量
  • 通配符 SSL
  • 配置 Cron 调度器
  • 配置 Mailhog
  • 配置 Minio
  • 端口
  • 共享你的环境
  • 多 PHP 版本
  • Web 服务器
  • 邮件
• 调试与性能分析
  • 使用 Xdebug 调试 Web 请求
  • 调试 CLI 应用程序
  • 使用 Blackfire 为应用程序分析性能
• 网络接口
• 扩展 Homestead
• 更新 Homestead
• 针对虚拟机提供器的特殊设置
  • VirtualBox

介绍

Laravel 致力于让整个 PHP 开发体验变得更愉快，这其中也包括你的本地开发环境。Vagrant 提供了一种简单、优雅的方式来管理和配置虚拟机。

Laravel Homestead 是 Laravel 官方预封装的 Vagrant Box，它为你提供了一个完美的开发环境，让你不需要再本地开发机器上安装 PHP、Web 服务器以及其他的服务器软件。你再也不用担心会弄乱你的操作系统了！Vagrant Box 完全是一次性的。如果出现问题，你可以在几分钟内删除并重新创建 Box！

Homestead 可以在任何 Windows、Mac 或 Linux 系统上运行，它预装好了 Nginx、PHP、 MySQL 、PostgreSQL、 Redis 、 Memcached 、Node 以及开发令人惊叹的 Laravel 应用程序所需的所有其他软件。

注意：如果你使用的是 Windows，你可能需要启用硬件虚拟化（VT-x）。该功能通常需要通过您的 BIOS 启用。如果您在 UEFI 系统上使用 Hyper-V，则可能还需要禁用 Hyper-V 才能访问 VT-x。

内置软件

• 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 for MySQL or MariaDB database snapshots
• Sqlite3
• PostgreSQL (9.6, 10, 11, 12)
• 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 Utilities

安装与设置

第一步

在你启动 Homestead 环境之前，你必须安装 VirtualBox 6.x, VMWare, Parallels 或 Hyper-V 以及 Vagrant。以上所有软件均针对不同的操作系统提供了易于使用的可视化安装包。

若要使用 VMware 提供器，你需要购买 VMware Fusion / Workstation 和 VMware Vagrant plug-in。 虽然它不是免费的，但是 VMware 可以提供更快的共享文件夹性能。

若要使用 Parallels 提供器，你需要安装免费的 Parallels Vagrant plug-in。

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

安装 Homestead Vagrant Box

一旦 VirtualBox / VMware 和 Vagrant 完成安装后，你可以在终端中使用下面的命令将 laravel/homestead box 添加到 Vagrant中。此举可能需要几分钟时间来下载 box，这取决于您的网速：

vagrant box add laravel/homestead

如果命令执行失败，请确保您安装了最新的 Vagrant。

注意：Homestead 会定期发布「alpha」 / 「beta」box 用于测试，这可能会影响 vagrant box add 命令。如果您在运行 vagrant box add 时遇到问题，您可以运行 vagrant up 命令，Vagrant 尝试启动虚拟机的时候，将会下载正确的 box 。

安装 Homestead

你可以克隆代码到你的宿主机上以安装 Homestead。推荐您将代码克隆到您的「home」目录下的 Homestead 文件夹中，这样，Homestead box 就可以作为你的所有 Laravel 项目的主机：

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

由于 Homestead 的 master 分支并不总是稳定的，您应该使用打过标签的版本。您可以在 GitHub Release Page 找到最新的稳定版本。或者，您可以 checkout 最新稳定版本中的 release分支：

cd ~/Homestead

git checkout release

一旦你克隆了 Homestead 仓库，您可以运行 bash init.sh 命令以创建 Homestead.yaml 配置文件。Homestead.yaml 将会置于 Homestead 目录中：

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

// Windows...
init.bat

配置 Homestead

设置您的提供器

Homestead.yaml 文件中的 provider 键指定了将使用哪一个 Vagrant 提供器，例如：virtualbox，vmware_fusion，vmware_workstation，parallels 和 hyperv。你可以根据你的喜好设定之：

provider: virtualbox

配置共享文件夹

Homestead.yaml 文件中的 folders 属性列出了所有你想要与 Homestead 环境共享的文件夹。这些文件夹中的文件发生变化的时候，它们将会在您的本地机器与 Homestead 环境之间保持同步。您可按需配置多个共享文件夹：

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

注意：Windows 不要使用 ~/ 路径语法，而应该使用项目的完整路径，如 C:\Users\user\Code\project1.

您应该始终将各个项目映射到它们自己的文件夹映射，而不是映射整个 ~/code 文件夹。映射文件夹时，虚拟机保持跟踪文件夹中 每一个 文件的所有磁盘 IO。当文件夹中有大量文件时，此举可能影响性能。

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

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

注意：你不应该在使用 Homestead 的时候挂载 . （当前目录）。此举会导致 Vagrant 不会将当前文件夹映射到 /vagrant，并且在配置的时候可能会导致意外情况发生。

要启用 NFS ，您只需要在共享文件夹配置中添加一个简单的标识：

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

注意：在 Windows 上使用 NFS 时，你应该考虑安装 vagrant-winnfsd 插件。它将会为您正确处理 Homestead box 中的文件和目录的用户和用户组权限问题。

您也可以在 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 属性将允许您轻松的将「域名」映射到 Homstead 环境中的目录中去。Homestead.yaml 中包含了一个简单的站点配置。同样，您可以按需添加许多站点到您的 Homestead 环境中。Homsetad 能够为您开发每一个 Laravel 项目提供一个方便的、虚拟化环境：

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

如果您在启动了 Homestead box 后修改了 site 属性，您需要再次运行 vagrant reload --provision 命令以更新虚拟机中的 Nginx 配置。

注意：Homestead 脚本设计时，尽可能保持操作的幂等。当然，如果你在 provisioning 过程中遇到了问题，您可以通过 vagrant destroy && vagrant up 销毁和重构虚拟机。

启用/禁用服务

默认情况下，Homestead 启动了许多服务；当然，你可以在启动过程中自行指定要启用和禁用的服务。例如，你可以启用 PostgreSQL 禁用 MySQL：

services:
    - enabled:
        - "postgresql@12-main"
    - disabled:
        - "mysql"

指定的服务将根据其在 enabled 和 disabled 指令中的顺序启停。

主机名解析

Homstead 通过 mDNS 发布主机名来自动解析主机。如果你在 Homestead.yaml 文件中设置了 hostname: homestead ，则主机将会以 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 。添加到 hosts 文件中的记录如下：

192.168.10.10  homestead.test

确保指定的 IP 地址和您在 Homestead.yaml 文件中指定的 IP 地址一致。一旦您将域名添加到 hosts 文件中，且启动了 Vagrant box，您就可以通过浏览器访问站点了：

http://homestead.test

启动 Vagrant Box

按照你的喜好编辑完 Homestead.yaml 之后，在 Homestead 目录下执行 vagrant up 命令，Vagrant 会启动虚拟机并自动配置你的共享文件夹和 Nginx 站点。

如需销毁虚拟机，请使用 vagrant destroy --force 命令。

根据项目安装

除了全局安装 Homestead 并且在所有项目共享相同的 Homestead box 之外，你可以为每个项目配置 Homestead 实例。通过在项目下创建 Vagrantfile，其他的项目成员只需运行 vagrant up 就能拥有相同的开发环境。

要将 Homestead 直接安装到项目中，需要使用 Composer 命令：

composer require laravel/homestead --dev

Homestead 安装之后， 使用 make 命令在项目根目录中生成 Vagrantfile 和 Homestead.yaml 文件。make 命令会自动配置 Homestead.yaml 文件中的 sites 和 folders 指令。

Mac / Linux:

php vendor/bin/homestead make

Windows:

vendor\\bin\\homestead make

接下来，在命令行终端运行 vagrant up 命令，然后在浏览器中访问 http://homestead.test。记住，如果你没有使用自动 主机名解析，在访问之前你仍然需要在 /etc/hosts 文件中添加你的 homestead.test 记录或者其他的域名。

安装可选功能

安装可选功能可以在 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.9.0
    - 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.yaml 文件中添加 elasticsearch 选项并指定支持的版本号。可以仅包含主版本，也可以是某个具体的版本号（major.minor.patch）。默认安装会创建一个名为「homestead」的集群。 注意永远不要赋予 Elasticsearch 超过操作系统一半的内存，因此请保证你的 Homestead 至少分配了两倍于 Elasticsearch 的内存。

提示：你可以查看 Elasticsearch documentation 文档学习如何自定义你的配置。

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 机器，以确保新的别名在机器上生效。

Daily Usage

Accessing Homestead Globally

有时你可能想在文件系统的任意路径都能运行 vagrant up 命令启动 Homestead 虚拟机。在 Mac / Linux 系统上可以在 Bash 配置文件（ ~/.bash_profile ）中添加 Bash 函数 。在 Windows 上， 你可以添加「批处理」文件到 PATH 。这些脚本允许你在系统的任何位置运行 Vagrant 命令并自动将该命令指向 Homestead 的安装路径：

Mac / Linux

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

确保将该函数中的 ~/Homestead 路径调整为实际的 Homestead 安装路径。这样你就可以在系统的任意位置运行 homestead up 或 homestead ssh 等命令。

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 虚拟机，因此请考虑将上面的「函数」添加到主机以便快速地以 SSH 方式连接到 Homestead 虚拟机。

连接数据库

homestead 默认已经在虚拟机中为 MySQL 和 PostgreSQL 数据库做好了配置。要从主机的数据库客户端连接到 MySQL 或 PostgreSQL ，应该连接到 127.0.0.1 ，端口 33060 （MySQL） 或 54320 （PostgreSQL）。用户名和密码分别是 homestead / secret 。

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

数据库备份

当你的 Vagrant 盒子销毁时，Homestead 能自动备份你的数据库。为了利用这个功能，你必须使用 Vagrant 2.1.0 或者更高的版本。或者，如果你使用一个旧版本的 Vagrant，你必须安装 vagrant-triggers 插件。要开启自动数据库备份，需添加如下的行到你的 Homestead.yaml 文件：

backup: true

一旦配置了，当 vagrant destroy 命令被执行时，Homestead 将导出你的数据库到 mysql_backup 和 postgres_backup 目录。如果你使用 每个项目安装 方法，则可以在克隆的 Homestead 或者在你的项目根目录中找到这些目录。

数据库快照

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

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

由于 lmm 会与 LVM 进行交互，所以必须以 root 身份运行。要了解所有命令，可以在 Homestead 虚拟机中通过 sudo 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』文件，你可能还需要添加新的站点到该文件中：

192.168.10.10  homestead.test
192.168.10.10  another.test

一旦这个站点被添加，从你的 Homestead 目录运行 vagrant reload --provision 命令。

站点类型

Homestead 支持多种类型的站点，允许你轻松运行不是基于 Laravel 的项目。例如，我们可以使用 symfony2 站点类型轻松地添加一个 Symfony 应用到 Homestead：

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 用户更新环境。

通配符 SSL

在 Homestead.yaml 文件的 sites 部分，可以给每个站点定义一个自签名 SSL 证书。如果你想给某个网站生成一个通配符 SSL 证书，可以通过添加 wildcard 配置项来实现。默认情况下，网站会使用通配符证书 而不是 特定域证书

- map: foo.domain.test
  to: /home/vagrant/domain
  wildcard: "yes"

如果 use_wildcard 配置项设置为 no，通配符证书会生产但是不会使用。

- map: foo.domain.test
  to: /home/vagrant/domain
  wildcard: "yes"
  use_wildcard: "no"

配置 Cron 定时计划

Laravel 提供了一种很方便的设置 定时计划作业 的方式，只需每分钟运行一次 schedule:run Artisan 命令。scheduler: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_MAILER=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://localhost:9600/ 访问 Minio 控制面板。默认的 access key 是 homestead，secret key 是 secretkey。当访问 Minio 时，您应该使用 us-east-1 区域。

要使用 Minio ，您需要调整 config/filesystems.php 配置文件中的 S3 存储配置。您只需要在 存储配置中添加 use_path_style_endpoint 选项，并将 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://localhost:9600

要配置 buckets，请在您的 Homestead 配置文件中添加 buckets 指令：

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
• PostgreSQL: 54320 → 转发至 5432
• MongoDB: 27017 → 转发至 27017
• Mailhog: 8025 → 转发至 8025
• Minio: 9600 → 转发至 9600

转发额外的端口

如果有需要，您亦可转发其他端口到 Vagrant box，同时指定其协议：

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

共享您的环境

有时，您可能希望跟您的同事共享您的工作内容。Vagrant 内置了一个通过 vagrant share 的方法实现之；但是，若您在 Homestead.yaml 文件中配置了多站点则无法正常工作。

要解决这个问题，Homestead 包含了自己的 share 命令。通过 vagrant ssh 进入到您的 Homestead 机器，然后运行 share homestead.test 以实现之。这将从您的 Homestead.yaml 配置文件共享 homestead.test 站点。 您可以用其他已经配置过的站点代替 homestead.test ：

share homestead.test

在运行这个命令之后，您的屏幕上将出现 Ngrok ，它包含了活动日志和共享站点的可公开访问的 URL。如果您想自定义区域，子域，或者是 Ngrok 的运行选项，您可以将其添加至 share 命令：

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

注意：记住，Vagrant 本质上是不安全的，并且当您运行 share 命令时将会是您的虚拟机暴露在互联网中。

多版本 PHP

Homestead 6 引入了在同一个虚拟机上支持多个版本的 PHP 。您可以在 Homestead.yaml 文件中指定用于站点的 PHP 的版本。可用的 PHP 版本包括：「5.6」, 「7.0」, 「7.1」, 「7.2」, 「7.3」（默认）：

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

此外，您可以在 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 Servers

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

flip

邮件

Homestead 包含了 Postfix 邮件转发代理，默认监听 1025 端口。所以，您可以指定您的应用使用 localhost 端口为 1025 的 smtp 邮件驱动。这样，Postfix 将接管所有的邮件发送，并由 Mailhog 捕获，您可以在浏览器中打开 http://localhost:8025 查看您发送的邮件。

调试 & 分析

使用 Xdebug 调试 Web 请求

Homestead 包含了 Xdebug 的逐步调试功能。例如，您可以在浏览器中加载某个页面，PHP 将会连接到您的 IDE 以便允许对运行的代码进行检查和修改。

默认情况下，Xdebug 已经运行并且准备好了接受请求。若您想要在 CLI 中启用 Xdebug ，请在您的 Vagrant box 中运行 sudo phpenmod xdebug 命令。接下来，按照 IDE 的指示以启动调试。最后，可通过浏览器扩展或 bookmarklet 配置浏览器🛫 Xdebug 。

注意：Xdebug 将会导致 PHP 运行缓慢。要禁用 Xdebug ，请在您的 Vagrant box 中运行 sudo phpdismod xdebug 命令并重启 FPM 服务。

调试 CLI 应用

要调试 CLI 应用，请在您的 Vagrant box 中使用 xphp 命令：

xphp path/to/script

自动启动 Xdebug

当发送请求到 Web 服务器的调试功能进行测试时，自动启动调试要比通过自定义头或修改 cookie 以触发调试过程要方便得多。要设置 Xdebug 自动启动，请参照如下的配置修改您的 Vagrant box 中的 /etc/php/7.x/fpm/conf.d/20-xdebug.ini 文件：

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

使用 Backfire 进行应用分析

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 为分析应用提供了各种各样的方案，包含了 CLI 工具和浏览器扩展。详细信息可查阅 Blackfire 文档 。

Profiling PHP Performance Using XHGui

XHGui 是一个审阅您的 PHP 应用性能的图形化界面的工具。要启用 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"

要启用 桥接 接口，请配置 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 文件来完成，在这个文件中，你可以做一些自己喜欢的定制化工作；不过，注意不要把 user-customizations.sh 文件提交到代码仓库中。

更新 Homestead

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

vagrant destroy

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

git fetch

git pull origin release

这些命令从 GitHub 仓库拉取最新的 Homestead 代码，获取最新的标记，然后检出最新的标记版本。你能在 GitHub 版本页面 找到最新稳定的版本。

如果你通过你的项目的 composer.json 安装 Homestead，你应当确保你的 composer.json 包含 "laravel/homestead": "^11" 并更新你的依赖项：

composer update

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

vagrant box update

然后，在 Homestead 目录下执行 bash init.sh 命令更新额外的配置文件。命令行将询问你是否要覆盖已经存在的 Homestead.yaml，after.sh 和 aliases 文件：

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

// Windows...
init.bat

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

vagrant up

针对 Provider 的特殊设置

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

• Homestead