Laravel Homestead

简介
- 预装软件
安装 & 配置
常见用法
网络类型
扩展 Homestead
更新 Homestead
提供者特殊设置
- VirtualBox

简介

Laravel 力图让整个 PHP 开发体验更加愉快，包括您的本地开发环境。Vagrant 提供了一种简单、优雅的方式来管理和配置虚拟机。

Laravel Homestead 是一个官方预装的 Vagrant Box，它提供了一个完美的开发环境，您不用在本地安装 PHP、Web 服务器或任何其它服务软件。Vagrant Box 完全是一次性的，因此不用担心会弄乱您的操作系统！如果哪里出问题了，可以在几分钟内删除并重新创建一个 Box！

Homestead 可以在任何 Windows、Mac 或 Linux 系统上运行，它包含了 Nginx Web 服务器，PHP 7.3，PHP 7.2，PHP 7.1，PHP 7.0，PHP 5.6，MySQL，PostgresSQL，Redis，Memcached，Node 以及其它开发 Laravel 应用所需的东西。

如果使用的是 Windows，可能需要在 BIOS 中启用硬件虚拟化（VT-x）。如果在 UEFI 系统上使用 Hyper-V，可能还需要禁用 Hyper-V 才能启用 VT-x。

预装软件

Ubuntu 18.04
Git
PHP 7.3
PHP 7.2
PHP 7.1
PHP 7.0
PHP 5.6
Nginx
Apache（可选）
MySQL
MariaDB（可选）
Sqlite3
PostgreSQL
Composer
Node（包括 Yarn，Bower，Grunt 和 Gulp）
Redis
Memcached
Beanstalkd
Mailhog
Neo4j（可选）
MongoDB（可选）
Elasticsearch（可选）
ngrok
wp-cli
Zend Z-Ray
Go
Minio

安装 & 配置

第一步

在启动 Homestead 环境之前，您必须安装 VirtualBox 5.2，VMWare，Parallels 或 Hyper-V 中的一个虚拟机软件，然后安装 Vagrant。上述软件都为主流操作系统提供了便于使用的图形化安装程序。

如果使用 VMware 作为虚拟机提供者，您需要同时购买 VMware Fusion / Workstation 以及 VMware Vagrant 插件。虽然 VMware 不是免费的，但 VMware 可以提供更快的共享文件夹性能。

如果使用 Parallels 作为虚拟机提供者，您需要安装 Parallels Vagrant 插件。它是免费的。

由于 Vagrant 的限制，使用 Hyper-V 作为虚拟机提供者时会忽略所有网络设置。

安装 Homestead Vagrant Box

安装好 VirtualBox / VMware 和 Vagrant 后，可以在终端使用如下命令将 laravel/homestead Box 添加到 Vagrant 中。下载 Box 可能需要几分钟的时间，具体取决网络连接速度：

vagrant box add laravel/homestead

如果上面的命令运行失败，请确保当前安装的 Vagrant 是最新版本。

安装 Homestead

可以通过克隆 Git 仓库安装 Homestead。建议您将代码仓库克隆到用户「home」目录下的 Homestead 文件夹中，这样就可以将 Homestead Box 作为所有 Laravel 项目的虚拟主机：

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

由于 Homestead 的 master 分支存在不稳定性，因此应使用带标签的稳定版本。可以在 Github 发布页面上获取最新的稳定版本。

cd ~/Homestead

// 克隆需要的版本
git checkout v7.18.0

克隆 Homestead 代码仓库后，在 Homestead 目录下运行 bash init.sh 命令创建 Homesstead.yaml 配置文件。Homesstead.yaml 文件位于 Homestead 目录中：

// Mac / Linux
bash init.sh

// Windows
init.bat

配置 Homestead

设置提供者

Homestead.yaml 文件里的 provider 参数用于指定 Vagrant 使用哪个虚拟机提供者：virtualbox、vmware_fusion、vmware_workstation 或者 parallels。您可以根据个人喜好设置：

provider: virtualbox

配置共享文件夹

Homestead.yaml 文件里的 folders 属性列出了所有和 Homestead 虚拟环境共享的文件夹。如果共享文件夹中的文件发生更改，会在本地计算机和 Homestead 虚拟环境之间保持同步。可以根据需要配置多个共享文件夹：

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

添加少数几个站点时，没什么问题。不过，随着站点数量的增加，可能会导致性能问题。在低配置计算机上或者当项目包含大量文件时尤其明显。如果遇到了此问题，可以尝试为每个项目单独指定共享文件夹：

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

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

要启用 NFS，只需在同步的文件夹配置中添加一个标识：

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

使用 NFS 时，建议您安装 vagrant-bindfs 插件。该插件会帮您维护好 Homestead Box 中文件或目录的正确用户／用户组权限。

还可以传递 Vagrant 共享文件夹支持的任何选项，只需将其列在 options 下面即可：

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

配置 Nginx 站点

不熟悉 Nginx？没关系。sites 属性可以帮您轻松将 域名 映射到 Homestead 环境的文件夹上。Homestead.yaml 文件中有示例站点配置。当然，也可以添加多个站点到 Homestead 环境。Homestead 能同时为多个 Laravel 项目提供虚拟化环境：

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

如果配置好 Homestead Box 后更改了 sites 属性，那么应再次运行 vagrant reload --provision 更新虚拟机上的 Nginx 配置。

Hosts 文件

必须将在 Nginx 站点中添加的「域名」也添加到本地计算机的 hosts 中。hosts 文件会将 Homestead 站点的请求重定向到 Homestead 虚拟机。在 Mac 或 Linux 上，该文件位于 /etc/hosts。在 Windows 上，位于 C:\Windows\System32\drivers\etc\hosts。添加的内容如下：

192.168.10.10  homestead.test

请确保列出的 IP 地址是在 Homestead.yaml 文件中设置的 IP 地址。将域名添加到 hosts 文件并启动 Vagrant Box 后，就可以通过 Web 浏览器访问该站点了：

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.app。别忘了，同样需要在 /etc/hosts 文件中为 homestead.test 或其它使用的域名添加域名解析记录。

安装 MariaDB

如果您要使用 MariaDB 而不是 MySQL，可以在 Homestead.yaml 文件中增加一个 mariadb 选项。该选项会删除 MySQL 并安装 MariaDB。MariaDB 只是作为 MySQL 的替代品，因此依然可以在应用的数据库配置中使用 mysql 数据库驱动：

box: laravel/homestead
ip: "192.168.10.10"
memory: 2048
cpus: 4
provider: virtualbox
mariadb: true

安装 MongoDB

要安装 MongoDB 社区版，可以在 Homestead.yaml 文件中更新以下选项：

mongodb: true

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

安装 Elasticsearch

要安装 Elasticsearch，可以在 Homestead.yaml 文件中添加 elasticsearch 选项并指定一个支持的版本，可以是主版本号或者具体的版本号（主版本.次版本.修订版本）。默认安装会创建一个名为「homestead」的集群。分配给 Elasticsearch 的内存不应超过操作系统内存的一半，所以确保分配 Homestead 虚拟机的内存至少是 Elasticsearch 的两倍：

box: laravel/homestead
ip: "192.168.10.10"
memory: 4096
cpus: 4
provider: virtualbox
elasticsearch: 6

可以查看 Elasticsearch 文档了解如何自定义相关配置。

安装 Neo4j

Neo4j 是一个图形化数据库管理系统。要安装 Neo4j 社区版，可以更新 Homestead.yaml 文件中的如下配置项：

neo4j: true

默认安装 Neo4 时会将数据库用户名设置为 homestead，对应的密码为 secret。可以通过 http://homestead.test:7474 在浏览器中访问 Neo4。7687（Bolt），7474（HTTP）以及 7473（HTTPS）端口已准备好处理来自 Neo4j 客户端的请求。

别名

可以为 Homestead 虚拟机中的 Bash 命令添加别名，只需要修改 Homestead 目录下的 aliases 文件：

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

更新 aliases 文件后，需要使用 vagrant reload --provision 命令重新加载 Homestead 虚拟机配置，以确保新的别名在虚拟机上生效。

常见用法

全局安装

如果想要在文件系统的任何地方都可以使用 vagrant up 命令启动 Homestead，可以在 Mac / Linux 系统的 Bash 配置文件中添加 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 连接虚拟机。

不过，您可能会频繁地使用 SSH 连接 Homestead 主机，因此可以考虑和上面一样添加一个「函数」来快速通过 SSH 连接 Homestead 虚拟机。

连接数据库

MySQL 和 PostgreSQL 都配置了开箱即用的数据库 homestead。为了方便使用，Laravel 中的 .env 配置默认使用该数据库。

要在主机上使用数据库客户端连接到 MySQL 或 PostgreSQL，应该连接 127.0.0.1 和 33060（MySQL）或 54320（PostgreSQL）端口。账号和密码分别是 homestead／secret。

从主机连接到数据库时，只能使用这些非标准端口。但是 Laravel 数据库配置文件使用默认的 3306 和 5432 端口，因为 Laravel 运行在虚拟机内部。

数据库备份

当删除 Vagrant Box 时，Homestead 会自动备份数据库。要使用该功能，必须安装 Vagrant 2.1.0 或更高版本。或者，如果您使用的是 Vagrant 的旧版本，则需要安装 vagrant-triggers 插件。要自动启用数据库备份，可以在 Homestead.yaml 文件中添加下面一行：

backup: true

配置后，当执行 vagrant destroy 命令时，Homestead 会将数据库导出到 mysql_backup 和 postgres_backup 目录中。为单个项目安装时，在克隆 Homestead 的目录或者项目根目录下也会看到这些目录。

添加站点

Homestead 环境配置完成并成功运行后，可能想为 Laravel 应用增加其它的 Nginx 站点。可以在单个 Homestead 环境中运行多个 Laravel 程序。要添加网站，只需将站点配置信息添加到 Homestead.yaml 文件中：

sites:
    - map: homestead.test
      to: /home/vagrant/code/Laravel/public
    - map: another.test
      to: /home/vagrant/code/another/public

如果 Vagrant 没有自动管理「hosts」文件，您可能需要手动把新站点添加到此文件中，就像这样：

192.168.10.10  homestead.test
192.168.10.10  another.test

添加站点后，在 Homestead 目录下运行 vagrant reload --provision 命令就可以应用新的更改。

站点类型

Homestead 支持多种站点，让您轻松运行那些不基于 Laravel 的项目。例如，我们可以使用 symfony2 在 Homestead 中添加一个 Symfony 应用：

sites:
    - map: symfony2.test
      to: /home/vagrant/code/Symfony/web
      type: "symfony2"

可用的站点类型包括：apache，apigility，expressive，laravel（默认），proxy，silverstripe，statamic，symfony2，symfony4 和 zf。

站点参数

还可以使用 params 指令向站点添加其它 Nginx fastcgi_param 值。例如，添加一个值为 BAR 的 FOO 参数：

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

环境变量

可以在 Homestead.yaml 文件中添加并设置全局环境变量：

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

更新 Homestead.yaml 后，要运行 vagrant reload --provision 来重新加载配置。它会更新所有已安装版本的 PHP 和 vagrant 用户的相关环境。

配置任务调度

Laravel 提供了便捷的方式来执行任务调度，运行 Artisan 命令 schedule:run，它会每分钟运行一次。schedule:run 命令会检查定义在 App\Console\Kernel 类中的任务调度，并评估任务是否应该被运行。

如果想为 Homestead 站点运行 schedule:run 命令，那么在定义站点时要将 schedule 选项设置为 true：

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

该站点的任务调度会被定义在虚拟机的 /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 文件中：

minio: true

默认，Minio 可以通过 9600 端口访问。也可以使用 http://homestead: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://homestead: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 → 转发到 To 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 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.1，7.2 和 7.3（默认）：

sites:
    - map: homestead.test
      to: /home/vagrant/code/Laravel/public
      php: "5.6"

此外，还可以在命令行界面使用任何支持的 PHP 版本：

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

Web 服务器

Homestead 默认使用 Nginx 作为 Web 服务器。但是，如果站点类型指定了 apache，将会安装 Apache。尽管两种 Web 服务器可以同时安装，但不能 同时运行。flip Shell 命令用于在 Web 服务器之间切换进程。flip 命令会自动确定哪个 Web 服务器正在运行，关闭该服务器，并启动另一个 Web 服务器。要使用该命令，可以通过 SSH 登录 Homestead，然后在终端运行以下命令：

flip

邮件

Homestead 包含了 Postfix 邮件传输代理，默认监听 1025 端口。因此，您需要修改 smtp 驱动使用 localhost 的 1025 端口。接下来，所有发送的邮件都会被 Postfix 处理并被 Mailhog 获取到。要查看您发送的邮件，可以在浏览器中访问 http://localhost:8025。

网络类型

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 pkg::Options::="--force-confold" \
    install your-package

更新 Homestead

通过两个简单的步骤即可更新 Homestead。首先，使用 vagrant box update 命令更新 Vagrant Box：

vagrant box update

接下来，更新 Homestead 的源代码。如果是克隆的仓库，可以在克隆的仓库下面执行 git pull origin master。

如果是通过项目的 composer.json 安装的 Homestead，请确保 composer.json 包含 "laravel/homestead": "^7"，然后更新依赖：

composer update

提供者特殊设置

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