Homestead

5.7

8.5 8.x 7.x 6.x 5.8 5.7 5.6 5.5 5.4 5.3 5.2 5.1

本文档最新版为 8.5，旧版本可能放弃维护，推荐阅读最新版！

Laravel Homestead

介绍
安装与设置
日常使用
网络接口
扩充 Homestead
更新 Homestead
提供器的特殊设置
- VirtualBox

简介

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 5.2、 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

你还可以通过克隆代码来安装 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 命令来创建 Homestead.yaml 配置文件。此 Homestead.yaml 文件将被放在 Homestead 目录中:

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

// Windows...
init.bat

配置 Homestead

设置提供器

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

provider: virtualbox

配置共享文件夹

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

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

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

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"

{note} 当使用 NFS, 建议你安装 vagrant-bindfs 扩展插件. 这个插件会替你处理 Homestead box 中的文件或目录权限的问题。

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

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 虚拟机后更改了 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 文件中所设置的。一旦你将将域名添加到 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 记录或者其他的域名。

安装 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 documentation 文档学习如何自定义你的配置。

安装 Neo4j

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

neo4j: true

默认安装的 Neo4j 会将数据库用户名设置为 homestead 对应的密码设置为 secret。要查看 Neo4j 可以在浏览器访问 http://homestead.test:7474。 Neo4j 对外提供了3个端口：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)中添加 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 数据库做好了配置。为了方便起见，Laravel 中的 .env 文件文件将框架配置成默认使用此数据库。

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

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

数据库备份

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

backup: true

配置好之后， Homestead 会在执行 vagrant destroy 命令时将数据库导出到 mysql_backup 和 postgres_backup 目录。这些目录可以在克隆 Homestead 的文件夹中找到或者如果你使用 per project installation 方法可以在项目的根目录中找到。

添加其他站点

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 的项目。例如，我们可以在 Homestead 使用 symfony2 站点类型，轻松的添加一个 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版本的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/code/Laravel/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

配置 Minio

Minio 是一个开源的对象存储服务器，具有与 Amazon S3 兼容的API。要安装 Minio ，可以通过下面的配置来修改你的 Homestead.yaml 文件

minio: true

默认 Minio 会在端口9600上运行。你可以访问 http://homestead:9600/ 来查看 Minio 控制面板。默认账户为homestead，默认密码为 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

端口

默认将以下端口转发到你的 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 → 转发至 To 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 版本

{注意} 这个功能只兼容 Nginx。

Homestead 6 引入了单个虚拟机多个 PHP 版本的支持。你可以在 Homestead.yaml 文件中站点配置下指定 PHP 版本。可用的版本有： "7.1", "7.2" 和 "7.3" （默认）：

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

另外，也支持在命令行中指定可用的 PHP 版本：

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

Web 服务器

Homestead 默认使用 Nginx 作为 web 服务器。然而，如果站点类型被设置为 apache 时，Apache 也会被安装。虽然两种 web 服务器可以同时存在，但它们不能同时运行。 flip shell 命令可以很方便地实现 web 服务器之间的切换。 flip 命令会自动检测当前运行的服务器类型，然后关闭它，再启动另外一类服务器。只需 SSH 进入你的 Homestead 虚拟机，在终端运行该命令即可：

flip

邮件

Homestead 包含 Postfix 邮件代理，默认端口是 1025 。所以，你可以让你的应用使用 smtp 邮件驱动在 localhost 端口是 1025。然后，所有发送的邮件会被 Postfix 处理然后被 Mailhog 接收。用浏览器打开 localhost:8025 去看你发的邮件。

网络接口

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。可在此脚本中，添加配置和自定义虚拟机所需的任何命令。

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

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

更新 Homestead

更新 Homestead 只需要两个简单的步骤。首先，运行 vagrant box update 更新 Vagrant box ：

vagrant box update

然后，你需要更新 Homestead 源代码。如果你使用 git 克隆仓库安装，你可以在仓库目录下运行 git pull origin master 命令。

如果你是通过项目 composer.json 文件安装的，你需要确保你的 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

本文章首发在网站上。

Homestead 5.7 8.5 8.x 7.x 6.x 5.8 5.7 5.6 5.5 5.4 5.3 5.2 5.1

Laravel Homestead

简介

内置软件

安装 & 设置

第一步

安装 Homestead Vagrant Box

安装 Homestead

配置 Homestead

设置提供器

配置共享文件夹

配置 Nginx 站点

Hosts 文件

启动 Vagrant Box

根据项目安装

安装 MariaDB

安装 MongoDB

安装 Elasticsearch

安装 Neo4j

别名

日常使用

全局可用的 Homestead

Mac / Linux

Windows

通过 SSH 连接

连接数据库

数据库备份

添加其他站点

站点类型

站点参数

环境变量

配置 Cron 调度器

配置 Mailhog

配置 Minio

端口

转发更多端口

共享你的环境

多 PHP 版本

Web 服务器

邮件

网络接口

扩充 Homestead

更新 Homestead

提供器配置

VirtualBox

natdnshostresolver

Windows 上的符号链接

Homestead

5.7

8.5 8.x 7.x 6.x 5.8 5.7 5.6 5.5 5.4 5.3 5.2 5.1

`natdnshostresolver`