* * * * *
[TOC]
## 简介
Laravel 致力于让整个 PHP 开发体验变得愉快， 包括你的本地开发环境。 [Vagrant](https://www.vagrantup.com/) 提供了一种简单，优雅的方式来管理和配置虚拟机。
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](https://www.virtualbox.org/wiki/Downloads)， [VMWare](https://www.vmware.com/)， [Parallels](https://www.parallels.com/products/desktop/) 或 [Hyper-V](https://docs.microsoft.com/en-us/virtualization/hyper-v-on-windows/quick-start/enable-hyper-v) 以及 [Vagrant](https://www.vagrantup.com/downloads.html). 上述软件均针对不同操作系统提供了易于使用的可视化安装包。
若要使用 VMware 提供器，你需要购买 VMware Fusion / Workstation 和 [VMware Vagrant plug-in](https://www.vagrantup.com/vmware)。虽然它不是免费的，但 VMware 可以提供更快的共享文件夹性能。
若要使用 Parallels 提供器，你需要安装 [Parallels Vagrant plug-in](https://github.com/Parallels/vagrant-parallels). 这是免费的。
由于受到 [Vagrant 限制](https://www.vagrantup.com/docs/hyperv/limitations.html) , 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 发行页](https://github.com/laravel/homestead/releases) 上找到最新的稳定版本：
~~~
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](https://www.vagrantup.com/docs/synced-folders/nfs.html)，只需要在共享的文件夹配置中添加一个简单的标志：
~~~
folders:
- map: ~/Code
to: /home/vagrant/Code
type: "nfs"
~~~
> {note} 使用 NFS 时，建议你安装 [vagrant-bindfs](https://github.com/gael-ian/vagrant-bindfs) 插件。这个插件会替你处理 Homestead Box 中的文件或目录权限问题。
你也可以通过在 `options` 下方列出 Vagrant 的 [共享文件夹](https://www.vagrantup.com/docs/synced-folders/basic_usage.html) 支持的任何选项：
~~~
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 文档](https://www.elastic.co/guide/en/elasticsearch/reference/current) 学习如何自定义你的配置。
### 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 任务](https://www.kancloud.cn/tonyyu/laravel_5_6/786249) 通过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](https://www.vagrantup.com/docs/networking/public_network.html) 接口,需要添加一个 `bridge` 设置并且把网络类型更改为 `public_network` ：
~~~
networks:
- type: "public_network"
ip: "192.168.10.20"
bridge: "en1: Wi-Fi (AirPort)"
~~~
启用 [DHCP](https://www.vagrantup.com/docs/networking/public_network.html), 只需要从配置中去将 `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
- Valet
- 部署
- 核心架构
- 请求周期
- 服务容器
- 服务提供者
- Facades
- Contracts
- 基础功能
- 路由
- 中间件
- CSRF 保护
- 控制器
- 请求
- 响应
- 视图
- URL
- Session
- 表单验证
- 错误
- 日志
- 前端开发
- Blade 模板
- 本地化
- 前端指南
- 编辑资源 Mix
- 安全相关
- 用户认证
- Passport OAuth 认证
- 用户授权
- 加密解密
- 哈希
- 重置密码
- 综合话题
- Artisan 命令行
- 广播系统
- 缓存系统
- 集合
- 事件系统
- 文件存储
- 辅助函数
- 邮件发送
- 消息通知
- 扩展包开发
- 队列
- 任务调度
- 数据库
- 快速入门
- 查询构造器
- 分页
- 数据库迁移
- 数据填充
- Redis
- Eloquent ORM
- 快速入门
- 模型关联
- Eloquent 集合
- 修改器
- API 资源
- 序列化
- 测试相关
- 快速入门
- HTTP 测试
- 浏览器测试 Dusk
- 数据库测试
- 测试模拟器
- 官方扩展包
- Cashier 交易工具包
- Envoy 部署工具
- Horizon
- Scout 全文搜索
- Socialite 社会化登录