Laravel Homestead

简介

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

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

Homestead 可以运行在任何 Windows、 Mac、 或 Linux 系统， 它包括了 Nginx web 服务器， PHP 7.3、 PHP 7.2、 PHP 7.1、 MySQL、PostgreSQL、Redis、 Memcached、 Node 以及你开发 Laravel 所需要的东西。

{note} 如果你使用的是 Windows, 你可能需要通过 BIOS 来启用硬件虚拟化 (VT-x)。如果你在 Hyper-V 系统上使用 UEFI 你可能还需要禁用 Hyper-V 以便访问 VT-x.

内置软件

  • Ubuntu 18.04
  • Git
  • PHP 7.3
  • PHP 7.2
  • PHP 7.1
  • Nginx
  • Apache (Optional)
  • MySQL
  • MariaDB (Optional)
  • Sqlite3
  • PostgreSQL
  • Composer
  • Node (With Yarn, Bower, Grunt, and Gulp)
  • Redis
  • Memcached
  • Beanstalkd
  • Mailhog
  • Neo4j (Optional)
  • MongoDB (Optional)
  • Elasticsearch (Optional)
  • ngrok
  • wp-cli
  • Zend Z-Ray
  • Go
  • Minio

安装 & 设置

第一步

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

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

若要使用 Parallels 提供器， 你需要安装 。它是免费的哦。

由于受到 Vagrant 限制, Hyper-V 提供程序会忽略所有的网络设置。

一旦将 VirtualBox / VMware 和 Vagrant 都安装好之后, 你可以在终端执行下面的命令将 laravel/homestead box 添加到 Vagrant 中安装。你可能需要几分钟的时间来下载 box ， 因为它取决于你的网络连接速度:

  1. vagrant box add laravel/homestead

如果这个命令失败了，请确保你安装的是最新版的 Vagrant。

安装 Homestead

你可以通过克隆代码来安装 Homestead。 建议将代码克隆到你的 "home" 目录下的 Homestead 文件夹中， 这样 Homestead box 就可以作为你的所有 Laravel 项目的主机：

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

因为 Homestead 的 master 分支并不是稳定的，你应该使用打过标签的稳定版本。你可以在 GitHub 发行页: 上找到最新的稳定版本:

  1. cd ~/Homestead
  3. // 克隆期望的发行版本...
  4. git checkout v8.0.1

一旦克隆 Homestead 代码完成以后, 在 Homestead 目录中使用 bash init.sh 命令来创建 Homestead.yaml 配置文件。 Homestead.yaml 文件将被放在 Homestead 目录中:

  1. // Mac / Linux...
  2. bash init.sh
  4. // Windows...
  5. init.bat

配置 Homestead

设置提供器

Homestead.yaml 文件中的 provider 参数决定了你用的是哪一个 Vagrant 提供器 : virtualbox, vmware_fusion, vmware_workstation, parallels 以及 hyperv。 你可以根据你的喜好来设置他们:

  1. provider: virtualbox

配置共享文件夹

Homestead.yaml 文件的 folders 属性里列出了所有与 Homestead 环境共享的文件夹。 这些文件夹中的文件如果发生变更，它们会保持本地机器与 Homestead 环境之间同步。 你可以根据需要配置多个共享文件夹:

  1. folders:
  2.     - map: ~/code
  3.       to: /home/vagrant/code

如果你只创建几个网站，这种通用的映射将运行的很好。但是，随着网站数量的不断增加，你可能会开始遇到性能问题。在包含大量文件的低性能机器或项目中，这个问题会非常明显。如果遇到此问题，请尝试将每个项目映射到自己的 Vagrant 文件夹:

  1. folders:
  2.     - map: ~/code/project1
  3.       to: /home/vagrant/code/project1
  5.     - map: ~/code/project2
  6.       to: /home/vagrant/code/project2

若要开启 NFS, 你只需要在共享的文件夹配置中添加一个简单的标志:

  1. folders:
  2.     - map: ~/code
  3.       to: /home/vagrant/code
  4.       type: "nfs"
{note} 当使用 NFS 时, 你最好使用 vagrant-winnfsd 扩展插件。 这个插件会替你处理 Homestead box 中的文件或目录权限的问题。

你也可以通过在 options 中列出 Vagrant's 的共享文件夹 支持的任何选项:

  1. folders:
  2.     - map: ~/code
  3.       to: /home/vagrant/code
  4.       type: "rsync"
  5.       options:
  6.           rsync__args: ["--verbose", "--archive", "--delete", "-zz"]
  7.           rsync__exclude: ["node_modules"]

配置 Nginx 站点

对 Nginx 不熟悉? 没关系。 sites 功能可以让你在 Homestead 上轻松的映射一个"域名"到一个文件夹。在 Homestead.yaml 文件中包含了一个简单的站点配置示例。同样，您可以根据需要为您的 Homestead 环境添加很多的站点。Homestead 可以为你正在开发的每个 Laravel 项目提供一个方便的虚拟化环境：

  1. sites:
  2.     - map: homestead.test
  3.       to: /home/vagrant/code/my-project/public

如果你在配置 Homestead 虚拟机后更改了 sites 选项，你需要再次运行 vagrant reload —provision 命令去更新虚拟机上的 Nginx 配置.

Hosts 文件

你必须将 Nginx 站点中所添加的域名添加到你本机的 hosts 文件中。 hosts 文件会将把访问你 Homestead 站点的请求重定向到你的 Homestead 虚拟机上。在 Mac 和 Linux 中，该文件的地址在 /etc/hosts，在 Windows 中位于C:\Windows\System32\drivers\etc\hosts。添加新站点的格式如下所示：

  1. 192.168.10.10  homestead.test

确保监听的 IP 地址是你在 Homestead.yaml 文件中所设置的。一旦你将将域名添加到 hosts 文件中并启动 Vagrant Box后，你就可以通过浏览器访问该站点了:

  1. http://homestead.test

启动 Vagrant Box

根据你的需求编辑完成 Homestead.yaml，在你的 Homestead 文件夹中运行 vagrant up 命令。Vagrant 将启动虚拟机并自动配置你的共享文件夹和 Nginx 站点。

若要删除虚拟机，只需要运行 vagrant destroy —force 命令。

根据项目安装

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

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

  1. composer require laravel/homestead --dev

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

Mac / Linux:

  1. php vendor/bin/homestead make

Windows:

  1. vendor\\bin\\homestead make

接下来，在命令行中运行 vagrant up 命令，然后在浏览器中访问 http://homestead.test 。 记住，在访问之前你仍然需要在 /etc/hosts 文件中添加你的 homestead.test 记录或者其他的域名。

安装 MariaDB

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

  1. box: laravel/homestead
  2. ip: "192.168.10.10"
  3. memory: 2048
  4. cpus: 4
  5. provider: virtualbox
  6. mariadb: true

安装 MongoDB

如果你需要安装 MongoDB 社区版， 你可以在 Homestead.yaml 文件中将配置修改为：

  1. mongodb: true

MongoDB 默认的安装方式会把数据库的用户名设置为 homestead ，默认密码为 secret。

安装 Elasticsearch

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

  1. box: laravel/homestead
  2. ip: "192.168.10.10"
  3. memory: 4096
  4. cpus: 4
  5. provider: virtualbox
  6. elasticsearch: 6
{tip} 你可以查看 文档学习如何自定义你的配置。

安装 Neo4j

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

  1. neo4j: true

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

别名

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

  1. alias c='clear'
  2. alias ..='cd ..'

更新完 aliases 文件后， 你应该使用 vagrant reload —provision 命令重启Homestead 虚拟机， 以确保新的别名在机器上可用。

日常使用

全局可用的 Homestead

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

Mac / Linux

  1. function homestead() {
  2.     ( cd ~/Homestead && vagrant $* )
  3. }

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

Windows

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

  1. @echo off
  3. set cwd=%cd%
  4. set homesteadVagrant=C:\Homestead
  6. cd /d %homesteadVagrant% && vagrant %*
  7. cd /d %cwd%
  9. set cwd=
  10. set homesteadVagrant=

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

通过 SSH 连接

你可以通过在 Homestead 目录下运行 vagrant ssh 终端命令以 SSH 的方式连接到虚拟机。

但是，你可能需要频繁连接 Homestead 虚拟机，因此请考虑将上面的「函数」添加到主机以便快速地以 SSH 方式连接到 Homestead 虚拟机。

连接数据库

homestead 默认已经在虚拟机中为 MySQL 和 PostgreSQL 数据库做好了配置。为了方便起见， Laravel 中的 .env 文件将框架配置成默认使用此数据库。

要从主机的数据库客户端连接到 MySQL 或 PostgreSQL ，应该连接到 127.0.0.1 ，端口 33060 （MySQL） 或 54320 （PostgreSQL）。用户名和密码分别是 homestead / secret 。

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

数据库备份

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

  1. backup: true

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

添加额外的站点

一旦你的 Homestead 环境已配置并运行，你可以为你的 Laravel 应用添加额外的 Nginx 站点。你可能希望在单个 Homestead 环境运行多个 Laravel 安装。要添加额外的站点，到 Homestead.yaml 文件中添加站点：

  1. sites:
  2.     - map: homestead.test
  3.       to: /home/vagrant/code/my-project/public
  4.     - map: another.test
  5.       to: /home/vagrant/code/another/public

如果 Vagrant 不能自动管理你的『hosts』文件，你可能还需要添加新的站点到该文件中：

  1. 192.168.10.10  homestead.test
  2. 192.168.10.10  another.test

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

站点类型

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

  1. sites:
  2.     - map: symfony2.test
  3.       to: /home/vagrant/code/my-symfony-project/web
  4.       type: "symfony2"

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

站点参数

你可以通过 params 站点指令添加额外的 Nginx fastcgi_param 值到你的站点。例如，我们添加一个值为 BAR 的 Foo 参数：

  1. sites:
  2.     - map: homestead.test
  3.       to: /home/vagrant/code/my-project/public
  4.       params:
  5.           - key: FOO
  6.             value: BAR

环境变量

你能通过添加如下的值到 Homestead.yaml 文件来设置全局环境变量：

  1. variables:
  2.     - key: APP_ENV
  3.       value: local
  4.     - key: FOO
  5.       value: bar

更新 Homestead.yaml 文件之后，确保通过运行 vagrant reload —provision 命令重新配置机器。这个将更新所有安装 的 PHP 版本的 PHP-FPM 配置并为 vagrant 用户更新环境。

配置定时计划

Laravel 提供了一种 计划定时作业 的方式，通过安排单个 schedule:run Artisan 命令去每分钟运行。schedule:run 命令将检查在你在 App\Console\Kernel 类中定义的计划来决定运行哪个作业。

如果你想为一个 Homestead 站点的 schedule:run 命令运行起来，在定义站点时，你可以设置 schedule 选项为 true：

  1. sites:
  2.     - map: homestead.test
  3.       to: /home/vagrant/code/my-project/public
  4.       schedule: true

站点的 Cron 作业将被定义在虚机的 /etc/cron.d 目录中。

Configuring Mailhog

Mailhog 允许你轻松地捕获外发的电子邮件并进行检查它，而实际上没有将发送邮件给收件人。开始使用时，使用以下的邮件设置更新你的 .env 文件：

  1. MAIL_DRIVER=smtp
  2. MAIL_HOST=localhost
  3. MAIL_PORT=1025
  4. MAIL_USERNAME=null
  5. MAIL_PASSWORD=null
  6. MAIL_ENCRYPTION=null

一旦 Mailhog 被配置，你可以在 http://localhost:8025 上访问 Mailhog 控制面板。

配置 Minio

Minio 是一个开源的对象存储服务器，具有与 Amazon S3 兼容的 API。要安装 Minio，用以下的配置选项更新你的 Homestead.yaml 文件：

  1. minio: true

默认情况下，Minio 在端口 9600 上是可用的。你可以访问 Minio 控制面板通过访问 http://homestead:9600。默认访问的键名是 homestead，同时默认的密钥是 secretkey。当访问 Minio 时，你应当总是使用 us-east-1。

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

  1. 's3' => [
  2.     'driver' => 's3',
  3.     'key' => env('AWS_ACCESS_KEY_ID'),
  4.     'secret' => env('AWS_SECRET_ACCESS_KEY'),
  5.     'region' => env('AWS_DEFAULT_REGION'),
  6.     'bucket' => env('AWS_BUCKET'),
  7.     'endpoint' => env('AWS_URL'),
  8.     'use_path_style_endpoint' => true
  9. ]

最后，确保你的 .env 文件有如下的选项：

  1. AWS_ACCESS_KEY_ID=homestead
  2. AWS_SECRET_ACCESS_KEY=secretkey
  3. AWS_DEFAULT_REGION=us-east-1
  4. AWS_URL=http://homestead:9600

为了配置存储桶，在 Homestead 配置文件中添加一个 buckets 指令：

  1. buckets:
  2.     - name: your-bucket
  3.       policy: public
  4.     - name: your-private-bucket
  5.       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 盒子，同时也指定他们的协议：

  1. ports:
  2.     - send: 50000
  3.       to: 5000
  4.     - send: 7777
  5.       to: 777
  6.       protocol: udp

共享你的环境

有时你希望共享你当前工作的内容跟同事或客户。Vagrant 有内置的方法通过 vagrant share 去支持这个；然而，如果在 Homestead.yaml 文件中有多个站点配置，这个将不会工作。

为了解决这个问题，Homestead 包含它自己的 share 命令。开始时，SSH 通过 vagrant ssh 进入你的 Homestead 机器并运行 share homestead.test。这个将从你的 Homestead.yaml 配置文件中分享 homestead.test 站点。当然，你可以将任何其它配置的站点替换为 homestead.test：

  1. share homestead.test

运行此命令之后，你将看到一个 Ngrok 屏幕出现，其中包含了活动日志和共享站点的可访问的 URLs。如果你想指定一个自定义的区域，子域，或者其它 Ngrok 运行时选项，你可以添加他们到你的 share 命令：

  1. share homestead.test -region=eu -subdomain=laravel
{note} 记住，Vagrant 本质上是不安全的，并且在运行 share 命令时将虚拟机显露到互联网。

多版本 PHP

Homestead 6 在同一个虚拟机上引入了对多个 PHP 版本的支持。你可以在你的 Homestead.yaml 文件中指定要用于给定站点的 PHP 版本。可用的 PHP 版本是：『7.1』，『7.2』和『7.3』（默认）：

  1. sites:
  2.     - map: homestead.test
  3.       to: /home/vagrant/code/my-project/public
  4.       php: "7.1"

另外，你可以通过 CLI 使用任何支持的 PHP 版本：

  1. php7.1 artisan list
  2. php7.2 artisan list
  3. php7.3 artisan list

Web 服务器

默认情况下，Homestead 使用 Nginx web 服务器。然而，如果 apache 是指定的一个站点类型，它能安装 Apache。同时两个 web 服务器在同时被安装，他们不能同时运行。flip 脚本命令可用来轻松处理 web 服务器之间的切换。flip 命令自动确定正在运行的 web 服务器，将其关闭。然后启动其它服务器。要使用这个命令，SSH 进入到你的 Homestead 机器并在终端运行命令：

  1. flip

邮件

Homestead 包括 Postfix 邮件传输代理，默认监听 1025 端口。因此，你可以指示你的应用程序在 localhost 端口 1025 上使用 smtp 邮件驱动。所有发送的邮件将由 Postfix 处理并由 Mailhog 捕获。要查看已发送的邮件，在 web 浏览器中打开 http://localhost:8025。

网络接口

Homestead.yaml 中的 networks 属性为 Homestead 环境配置网络接口。你可以根据需要配置多个接口：

  1. networks:
  2.     - type: "private_network"
  3.       ip: "192.168.10.20"

要开启一个 桥接 接口，配置 bridge 设置并改变 public_network 网络类型：

  1. networks:
  2.     - type: "public_network"
  3.       ip: "192.168.10.20"
  4.       bridge: "en1: Wi-Fi (AirPort)"

要开启 DHCP，仅从你的配置中移除 ip 选项：

  1. networks:
  2.     - type: "public_network"
  3.       bridge: "en1: Wi-Fi (AirPort)"

扩展 Homestead

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

当自定义 Homestead 时，Ubuntu 可能会询问你是否要保留程序包的原始配置或者用一个新的配置文件覆盖它。为了避免这种情况，你应该在安装软件包时使用以下的命令，以避免覆盖之前由 Homestead 编写的任何配置：

  1. sudo apt-get -y \
  2.     -o Dpkg::Options::="--force-confdef" \
  3.     -o Dpkg::Options::="--force-confold" \
  4.     install your-package

更新 Homestead

你能通过一些简单的步骤更新 Homestead。首先，你应当使用 vagrant box update 命令更新 Vagrant 盒子：

  1. vagrant box update

接下来，你需要去更新 Homestead 源代码。如果你克隆过仓库，你能在最初克隆仓库的位置运行如下的命令：

  1. git fetch
  3. git checkout v8.0.1

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

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

  1. composer update

最后，你将需要销毁和重新生成你的 Homestead 盒子去利用最新的 Vagrant 安装。为了实现这个，在你的 Homestead 目录运行如下的命令：

  1. vagrant destroy
  3. vagrant up

提供特殊设置

VirtualBox

natdnshostresolver

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

  1. provider: virtualbox
  2. natdnshostresolver: off

Windows 上的符号链接

如果符号链接在你的 Windows 机器上无法正常工作，你可能需要添加以下的块到 Vagrantfile 文件：

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