Homestead

5.6

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
提供器的特殊设置
- VirtualBox

简介

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

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

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

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

内置软件

Ubuntu 16.04
Git
PHP 7.2
PHP 7.1
PHP 7.0
PHP 5.6
Nginx
Apache (Optional)
MySQL
MariaDB (Optional)
Sqlite3
PostgreSQL
Composer
Node (With Yarn, Bower, Grunt, and Gulp)
Redis
Memcached
Beanstalkd
Mailhog
Elasticsearch (Optional)
ngrok

安装与设置

第一步

在启动 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

// Clone the desired release...
git checkout v7.1.2

克隆 Homestead 以后, 在 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
      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 的共享文件夹支持的任何选项：

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.20.20"
memory: 2048
cpus: 4
provider: virtualbox
mariadb: true

安装 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

{tip} 你可以查看 Elasticsearch 文档学习如何自定义你的配置。

Bash 命令别名

你可以通过修改 Homestead 目录中的 aliases 文件来添加 Bash 的命令别名到 Homestead 中：

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

在更新了 aliases 文件后，你应该使用 vagrant reload --provision 命令来重新配置 Homestead 。这将确保您的新命令别名可以正常使用。

日常使用

Homestead 全局操作

有时候你可能会想在主机任何目录下通过 vagrant up 命令来启动。在Mac / Linux 上通过添加一个 Base 函数到 Bash profile文件中。在 Windows 上需要通过增加一个批处理文件，并将路径添加到 PATH 环境变量中。这些脚本可以让你在系统任何位置运行 Vagrant 的所有命令，它始终会自动转到你的 Homestead 安装目录。

Mac / Linux

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

确保将示例中 ~/Homestead 改成你系统中 Homestead 实际安装目录。该函数一旦设置完成，你就可以在系统任何位置 hometead up、hometead 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 环境变量中。你就可以在系统任何位置 hometead up、hometead ssh 类似这样的命令。

通过 SSH 连接

在终端 Homestead 安装目录下运行 vagrant ssh 可以 SSH 连接你的虚拟主机。

但是，你可能需要频繁连接 Homestead 主机，建议在你的主机中使用上方的方法来快速连接 Homestead 主机。

连接数据库

在 Box 中已经为 MySQL 和 Postgres 配置好了一个数据库 homestead。为了更方便的使用它，Laravel 中的 .env 文件将框架配置成默认使用此数据库。

要从主机的数据库客户端连接到 MySQL 或 Postgres，就连接到 127.0.0.1和端口 33060 (MySQL) 或 54320 (Postgres)。账号密码分别是 homestead／secret

{note} 从主机连接到数据库时，只能使用这些非标准端口。而 Laravel 在虚拟机中运行时，仍旧使用 Laravel 数据库配置文件中的默认 3306 和 5432 端口。

增加更多网站

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, laravel (默认), proxy, silverstripe, statamic, symfony2, 和 symfony4.

站点参数

你还可以使用 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

端口

默认情况下，以下端口会被转发至 Homestead 环境：:

SSH: 2222 → 发送到 22
ngrok UI: 4040 → 发送到 4040
HTTP: 8000 → 发送到 80
HTTPS: 44300 → 发送到 443
MySQL: 33060 → 发送到 3306
PostgreSQL: 54320 → 发送到 5432
Mailhog: 8025 → 发送到 8025

转发更多端口

你可以根据需要转发更多端口给 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

{note} 谨记，Vagrant 本质上是不安全的。当你运行 share 命令时，你已经在互联网中暴露了你的虚拟机。

多PHP版本

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

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

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

Web 服务器

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

flip

网络接口

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 只需要两个简单步骤。首先，运行 vagrant box update 更新 Vagrant box ：

vagrant box update

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

如果你是通过项目 composer.json 文件安装的，你需要更新 Homestead 依赖为 "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.6 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

安装 Elasticsearch

Bash 命令别名

日常使用

Homestead 全局操作

Mac / Linux

Windows

通过 SSH 连接

连接数据库

增加更多网站

站点类型

站点参数

环境变量

配置 Cron 调度器

配置 Mailhog

端口

转发更多端口

共享你的环境

多PHP版本

Web 服务器

网络接口

Homestead 更新

提供器配置

VirtualBox

natdnshostresolver

Windows 上的符号链接

Homestead

5.6

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`