簡介

Laravel 致力於讓你在 PHP 開發過程中更加輕松愉快，這其中也包括本地開發環境的搭建。 Vagrant 提供了一種簡單、優雅的方式來管理和配置虛擬機。

Laravel Homestead 是一個官方預封裝的 Vagrant box，它為你提供了一個完美的開發環境，你無需在本地安裝 PHP ，web 服務器，或其他服務軟件。 Vagrant box 是完全一次性的，你不用擔心系統被搞亂！如果有什麽地方出錯了，你可以在幾分鐘內銷毀並重建 box ！

Homestead 可以運行在 Windows 、Mac 或 Linux 系統上，它裏面包含了 Nginx Web 服務器、PHP 7.1 、MySQL 、Postgres 、Redis 、Memcached 、Node ，以及一些有利於你開發 laravel 應用的其他程序。

如果你使用的是 Windows 系統，你可能需要啟用硬件虛擬化（VT-x）。這通常需要通過 BIOS 來啟用它。如果你在一個 UEFI 系統上使用 Hyper-V，您可能還需要禁用 Hyper-V 才能啟用 VT-x。

內置軟件

• Ubuntu 16.04
• Git
• PHP 7.1
• Nginx
• MySQL
• MariaDB
• Sqlite3
• Postgres
• Composer
• Node (With Yarn, Bower, Grunt, and Gulp)
• Redis
• Memcached
• Beanstalkd
• Mailhog
• ngrok

安裝與設置

第一步

在你使用 Homestead 環境之前，你必須先安裝 VirtualBox 5.1 、VMWare 或者 Parallels 中的一個，然後再安裝 Vagrant。上述軟件均提供了針對不同操作系統的可視化安裝包。

若要使用 VMware provider，你需要同時購買 VMware Fusion / Workstation 以及 VMware Vagrant 插件 的軟件授權，因為它們不是免費的。使用 VMware 的優勢是：可以獲得開箱即用的共享文件夾特性。

若要使用 Parallels provider，你需要安裝 Parallels Vagrant 插件 ，這是免費的。

安裝 Homestead Vagrant Box

當 VirtualBox / VMware 以及 Vagrant 安裝完成後，你可以使用以下命令將 laravel/homestead 這個 box 添加進你的 Vagrant 當中。 homestead box 的下載會花費你一點時間，具體的下載時長由網絡速度決定：

vagrant box add laravel/homestead

如果上面的命令運行失敗，請先確保你已經安裝了最新版本的 Vagrant。

• 如果使用國內網絡，可以復制終端上顯示的 homestead box 下載地址手動下載並重命名。例如重命名為 virtualbox-3.0.0.box。

然後，新建一個 metadata.json 文件，並寫入以下示例內容：

{
    "name": "laravel/homestead",
    "versions": 
    [
        {
            "version": "3.0.0",
            "providers": [
                {
                  "name": "virtualbox",
                  "url": "virtualbox-3.0.0.box"
                }
            ]
        }
    ]
}

最後，使用以下命令手動添加 box

vagrant box add metadata.json # 添加 box
vagrant box list # 列出所有 box

安裝 Homestead

你可以簡單使用 Git 克隆代碼倉庫的方式來安裝 Homestead。建議將克隆的代碼倉庫重命名為 Homestead ，並放置到你的「home」目錄中，如此一來 Homestead box 就能作為主機，為你的所有 Laravel 項目提供服務：

cd ~

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

由於 Homestead 的 master 分支並不是穩定分支，你應該檢出已經標簽過的穩定版本。你可以在 Github Release Page 找到最新的穩定版本。

cd Homestead

// 檢出所需要的版本...
git checkout v5.4.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

若要啟動 NFS ，只需要在共享文件夾的設置值中加入一個簡單的參數：

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

• 如果使用 NFS ，建議你安裝 vagrant-bindfs 插件。 這個插件會替你處理 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.app
      to: /home/vagrant/Code/Laravel/public

如果你在 Homestead box 配置之後更改了 sites 屬性，那麽應該重新運行 vagrant reload --provision 來更新 Nginx 配置到虛擬機上。

關於 Hosts 文件

你必須將在 Nginx sites 中所添加的「域名」也添加到你本機電腦的 hosts 上。 hosts 文件會將請求重定向至 Homestead 環境中設置的本地域名。在 Mac 或 Linux 上，該文件通常會存放在 /etc/hosts。在 Windows 上，則存放於 C:\Windows\System32\drivers\etc\hosts。設置內容如下所示：

192.168.10.10  homestead.app

請務必確認 IP 地址與 Homestead.yaml 文件中設置的相同。將域名設置在 hosts 文件之後，你就可以通過網頁瀏覽器訪問你的網站。

http://homestead.app

啟動 Vagrant Box

根據你的喜好完成 Homestead.yaml 編輯後，進入你的 Homestead 目錄並運行 vagrant up 命令。 Vagrant 就會根據 Homestead.yaml 裏的配置信息啟動，並為虛擬機設置共享文件夾和 Nginx 網站。

如果要移除虛擬機，你可以使用 vagrant destroy --force 命令

為每個項目分開安裝

除了在全局範圍內安裝 Homestead 環境，所有項目共享相同的 Homestead box 外，你還可以為每一個項目配置一個獨立的 Homestead 實例。通過傳遞 Vagrantfile ，可以實現為每個項目分別安裝上 Homestead ，其他項目成員只需要通過簡單的 vagrant up 即能跟你擁有一樣的 Homestead 環境。

要將 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.app 或其它想要使用的域名。

如果你希望使用 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

• 安裝 MariaDB 需要連接境外網絡，請確保網絡暢通！

常見用法

全局使用

有時候你希望在文件系統的任何地方都可以使用 vagrant up 命令啟動虛擬機，那麽你需要添加以下代碼到你的 Mac / Linux 系統的 Bash profile 文件裏面。對於 Windows 系統，您可以通過在 PATH 環境變量中添加「批處理」文件的方式來實現此目的。下面這些腳本讓你可以在文件系統的任何位置都能運行 Vagrant 命令，它相當於切換到 Homestead 目錄運行 Vagrant 命令：

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 主機，請考慮將上述「function」添加到你的主機，以便可以快速的通過 SSH 進入你的 Homestead box

連接數據庫

在 box 中已經為 MySQL 和 Postgres 配置好了一個開箱即用的數據庫 homestead ，為了更方便的使用它，Laravel 中的 .env 文件將這個數據庫設置成了框架默認使用的數據庫。

如果想要從你主機上的數據庫客戶端連接 MySQL 或 Postgres，可以通過 127.0.0.1 來使用端口 33060(MySQL) 或 54320(Postgres) 連接。賬號密碼分別是 homestead / secret

• 因為虛擬機做了端口轉發，所以在本機電腦上你應當只使用這些非標準的連接端口。但在 Laravel 數據庫配置文件中，你依然要使用默認的 3306 及 5432 連接端口。

增加更多網站

一旦 Homestead 環境配置完畢且成功運行後，你可能會想要為 Laravel 應用程序增加更多的 Nginx 網站。你可以在單個 Homestead 環境中運行多個 Laravel 程序。要添加額外的網站，只需將網站配置信息添加到您的 Homestead.yaml 文件中：

sites:
    - map: homestead.app
      to: /home/vagrant/Code/Laravel/public
    - map: another.app
      to: /home/vagrant/Code/another/public

如果 Vagrant 沒有自動管理你的「hosts」文件，你可能需要手動把新增的站點加入到「hosts」文件中：

192.168.10.10  homestead.app
192.168.10.10  another.app

當你的網站添加完成後，切換到 Homestead 目錄運行 vagrant reload --provision 命令就可以應用新的更改。

網站類型

Homestead 支持多種類型的網站，允許您輕松地運行那些不基於 Laravel 的項目。 例如，我們可以使用「symfony2」配置項，輕松地在 Homestead 中添加 Symfony 應用程序：

sites:
    - map: symfony2.app
      to: /home/vagrant/Code/Symfony/web
      type: symfony2

支持的站點類型有： apache、laravel（默認）、proxy、silverstripe、statamic、symfony2 和 symfony4。

網站參數

你還可以使用「params」配置項，添加額外的 Nginx fastcgi_param 值到你的網站。例如添加一個名稱為「FOO」值為「BAR」的額外配置。

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

配置 Cron 調度器

Laravel 提供了便利的方式來 調度 Cron 任務 ，通過 schedule:run Artisan 命令，調度便會在每分鐘被運行。 schedule:run 命令會檢查定義在你 App\Console\Kernel 類中調度的任務，判斷哪個任務該被運行。

如果你想為 Homestead 網站使用 schedule:run 命令，你需要在定義網站時將 schedule 選項設置為 true

sites:
    - map: homestead.app
      to: /home/vagrant/Code/Laravel/public
      schedule: true

該網站的 Cron 任務會被定義在虛擬機的 /etc/cron.d 文件夾中。

端口

默認情況下，以下本地電腦端口將會被轉發至 Homestead 環境：

• SSH: 2222 → Forwards To 22
• HTTP: 8000 → Forwards To 80
• HTTPS: 44300 → Forwards To 443
• MySQL: 33060 → Forwards To 3306
• Postgres: 54320 → Forwards To 5432
• Mailhog: 8025 → Forwards To 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.app。這會從你的 Homestead.yaml 配置文件中共享 homestead.app 站點。當然了，你也可以用其他已經配置的站點來代替 homestead.app。

share homestead.app

運行完命令之後，你可以看到一個包含活動日誌和共享站點外網訪問路徑的 Ngrok 界面。如果你想要自定義地區或者其他 Ngrok 選項，你可以添加到 share 命令後面：

share homestead.app -region=eu -subdomain=laravel

• 謹記，Vagrant 本質上是不安全的，當你運行 share 命令的時候，你會把你的虛擬機暴露在互聯網中。

多個 PHP 版本

• 這個特性僅與 Nginx 兼容。

Homestead 6 支持在同一個虛擬機上引入多個不同版本的 PHP。您需要在 Homestead.yaml 配置文件中為某個站點指明需要使用的 PHP 版本即可。 可用的 PHP 版本有：「5.6」、「7.0」、「7.1」

sites:
    - map: homestead.app
      to: /home/vagrant/Code/Laravel/public
      php: "5.6"

此外，您還可以通過 CLI 使用任何支持的 PHP 版本：

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

網絡接口

Homestead.yaml 文件裏的 networks 配置項允許你為 Homestead 環境配置網絡接口。您可以根據需要配置任意數量的接口：

networks:
    - type: "private_network"
      ip: "192.168.10.20"

想要配置一個 橋接 接口的話，增加 bridge 配置項，然後 type 填寫為 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 命令更新 Vgrant box :

vagrant box update

接下來。你需要更新 Homestead 的源代碼，如果你是通過克隆倉庫的方式來安裝的 Homestead ，你可以在你最初克隆倉庫的位置簡單的運行 git pull origin master 命令。

如果你已經通過你的項目中的 composer.json 文件安裝了 Homestead ，你應該確認你的 composer.json 文件中是否包含 "laravel/homestead: "^4" 並且還要更新依賴：

composer update

歷史版本

如果你需要一個舊版本的 PHP ，請在嘗試使用舊版本 Homestead 之前，先閱讀文檔 多個 PHP 版本。

你可以通過添加以下配置到你的 Homestead.yaml 文件來方便的覆蓋 Homestead 使用的 box 版本:

version: 0.6.0

例如：

box: laravel/homestead
version: 0.6.0
ip: "192.168.20.20"
memory: 2048
cpus: 4
provider: virtualbox

當你使用舊版本的 box 時，你需要確保 Homestead 源代碼的版本與之對應，下面的圖表展示了支持的 box 版本，以及與之對應的 Homestead 的源代碼版本和 box 所提供的 PHP 版本：

Provider 的特殊設置

VirtualBox

Homestead 默認將 natdnshostresolver 設置為 on。這允許 Homestead 使用你的主機系統中的 DNS 設置。如果你想重寫這行為，你可以在你的 Homestead.yaml 文件中添加下面這幾行：

provider: virtualbox
natdnshostresolver: off

Laravel 虛擬開發環境 Homestead