簡介

Laravel 為開發者提供了一套完善的重量級本地開發環境 —— Laravel Homestead。

Laravel Homestead 實際是一個打包好各種 Laravel 開發所需軟體和工具的 Vagrant 盒子（關於 Vagrant 盒子的釋義請參考 Vagrant 官方文件），該盒子為我們提供了一個優秀的開發環境，有了它，我們不再需要在本地環境安裝 PHP、Composer、Nginx、MySQL、Memcached、Redis、Node 等其它工具軟體，我們也完全不用再擔心誤操作搞亂作業系統 —— 因為 Vagrant 盒子是一次性的，如果出現錯誤，可以在數分鐘內銷燬並重新建立該 Vagrant 盒子！

為什麼說它是重量級的開發環境呢？誰用誰知道，要使用上這個開發環境，你需要安裝 Vagrant、VirtualBox，下載 Homestead 對應的 Vagrant 盒子，經歷一系列下載、安裝和配置之後才能使用（可能需要花費數小時），如果是 Mac 或 Linux 系統可能還比較順利，如果是 Windows 系統的話就得先燒柱香拜拜菩薩再開始，保佑一切順利，哈哈，開玩笑啦，不過 Windows 確實相對而言出問題的概率比較大。

有人要說了，聽上去這麼複雜，我就不用了，不過相信我吧，這點時間都會在日後因為 Homestead 強大完善的功能在開發過程中補回來，正所謂磨刀不誤砍柴功，Homestead 不僅為你提供了一整套日後開發所需要的工具，而且與 Laravel 配置檔案預設配置無縫結合，省去了很多配置的麻煩，此外，如果是在團隊中開發的話，Homestead 還為你們提供了一致的開發環境，避免因為不同開發人員使用的工具軟體版本不同造成線上的問題，這三個理由，我想足夠可以說服你了。

當然，如果你只是想簡單嚐鮮，不使用 Homestead 也無可厚非，畢竟 Mac 下有 Valet，Windows 下則可以使用 Xampp 之類的便捷工具包，但是如果是工程化開發，走正規軍路子還是推薦使用 Homestead。

注：如果你使用的是 Windows，需要開啟系統的硬體虛擬化（VT-x），這通常可以通過 BIOS 來開啟。如果你是在 UEFI 系統上使用 Hyper-V，則需要關閉 Hyper-V 以便可以訪問 VT-x。

預裝軟體

Homestead 可以執行在 Windows、Mac 以及 Linux 等主流作業系統上，預裝的軟體和工具列表如下：

• Ubuntu 16.04
• Git
• PHP 7.2
• PHP 7.1
• PHP 7.0
• PHP 5.6
• Nginx
• Apache（可選）
• MySQL
• MariaDB（可選）
• SQLite3
• PostgresSQL
• Composer
• Node（With Yarn, Bower, Grunt, and Gulp）
• Redis
• Memcached
• Beanstalkd
• Mailhog
• Elasticsearch（可選）
• ngrok

安裝 & 設定

首次安裝

在使用 Homestead 之前，需要先安裝 Virtual Box 5.2、VMWare、Parallels 或 Hyper-V （四選一，我們通常選擇 VirtualBox，因為只有它是免費的）以及 Vagrant，所有這些軟體包都為常用作業系統提供了一個便於使用的視覺化安裝器，通過安裝介面引導就可以完成安裝。

要使用 VMware 的話，需要購買 VMware Fusion（Mac） / Workstation（Windows） 以及 VMware Vagrant 外掛，儘管不便宜，一套下來要 1000 多塊人民幣，但是 VMware 可以提供更好的效能和體驗（廢話，不然誰用，不過考慮到這個價格，只能呵呵了）。

要使用 Parallels 的話，需要安裝 Parallels Vagrant 外掛，這是免費的（僅僅是外掛免費哈）。

由於 Vagrant 限制的因素，Hyper-V 提供者會忽略所有網路設定。

安裝 Homestead Vagrant 盒子

VirtualBox/VMWare 和 Vagrant 安裝好了之後，在終端中使用如下命令將
Homestead Vagrant 盒子 laravel/homesterad 新增到 Vagrant 中。下載該盒子將會花費一些時間，具體時間長短主要取決於你的網路連線速度：

vagrant box add laravel/homestead

如果上述命令執行失敗，需要確認 Vagrant 是否是最新版本。

執行命令會列出一個選擇列表，選擇 virtualbox 對應選項即可，然後進入漫長的下載等待，看看多喜人，還要6小時40分鐘才能下載完成，基本上一覺醒來的節奏，還是在使用了 VPN 翻牆的情況下，如果一直提示網路超時的話只能去 Vagrant 官網下載了：https://atlas.hashicorp.com/laravel/boxes/homestead/versions/0.5.0/providers/virtualbox.box，通過這種方式下載的話需要手動將其新增到 Vagrant：

vagrant box add laravel/homestead ~/Downloads/virtualbox.box

執行上述命令有可能報錯：

Check your Homestead.yaml file, the path to your private key does not exist.

解決辦法如下：

ssh-keygen -t rsa -b 4096 -C "[email protected]"
eval "$(ssh-agent -s)"
ssh-add -K ~/.ssh/id_rsa

再次執行上述命令即可新增成功：



安裝 Homestead

你可以通過克隆倉庫程式碼來實現 Homestead 安裝。將倉庫克隆到使用者目錄下的 Homestead 目錄，這樣 Homestead 盒子就可以作為所有其他 Laravel 專案的主機：

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

克隆完成後，你需要檢查 Homestead 的版本標籤，因為 master 分支不會總是穩定版本，你可以在 GitHub Release Page 查詢到最新穩定版本然後在本地將其檢出：

cd Homestead

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

接下來，在 Homestead 目錄下執行 bash init.sh 命令來建立 Homestead.yaml 配置檔案，生成的 Homestead.yaml配置檔案檔案位於當前 Homestead 目錄：

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

// Windows...
init.bat

配置 Homestead

設定 Provider

Homestead.yaml 檔案中的 provider 鍵表示使用哪個 Vagrant 提供者：virtualbox、vmware_fushion、 vmware_workstation、parallels 或 hyperv，你可以將其設定為自己選擇的提供者，當然對大部分人來說也沒得選：

provider: virtualbox

配置共享資料夾

Homestead.yaml 檔案中的 folders 屬性列出了所有主機和 Homestead 虛擬機器共享的資料夾，一旦這些目錄中的檔案有了修改，將會在本地和 Homestead 虛擬機器之間保持同步，如果有需要的話，你可以配置多個共享資料夾：

folders:
    - map: ~/Development
      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: ~/Development
      to: /home/vagrant/Code
      type: "nfs"

注：使用 NFS 的話，需要考慮安裝 vagrant-bindfs 外掛。該外掛可用於在 Homestead 盒子中為檔案和目錄維護正確的使用者/組許可權。

你還可以通過 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 中預設已經配置了一個示例站點。和共享資料夾一樣，你可以配置多個站點：

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

如果你是在 Homestead 盒子啟動之後進行了上述修改，需要執行 vagrant reload --provision 更新虛擬機器上的 Nginx 配置。

Hosts檔案

不要忘記把 Nginx 站點配置中的域名新增到本地機器上的 hosts 檔案中，該檔案會將對本地域名的請求重定向到 Homestead 虛擬機器，在 Mac 或 Linux上，該檔案位於 /etc/hosts，在 Windows 上，位於 C:\Windows\System32\drivers\etc\hosts，新增方式如下：

192.168.10.10 homestead.test

確保 IP 地址和你的 Homestead.yaml 檔案中列出的一致，一旦你將域名新增到 hosts 檔案，就可以在瀏覽器中通過該域名訪問站點了：

http://homestead.test

注：在真正可以訪問之前還需要通過 Vagrant 啟動虛擬機器上的 Homestead 盒子。

啟動 Vagrant 盒子

配置好 Homestead.yaml 檔案後，在 Homestead 目錄下執行 vagrant up 命令，Vagrant 將會啟動虛擬機器並自動配置共享資料夾以及 Nginx 站點，初次啟動需要花費一點時間進行初始化：



啟動之後，就可以在瀏覽器中通過 http://homestead.test 訪問 Laravel 應用了（前提是 Web 目錄下已經部署 Laravel 應用程式碼）：



要登入到該虛擬機器，使用 vagrant ssh 命令；關閉該虛擬機器，可以使用 vagrant halt 命令；銷燬該虛擬機器，可以使用 vagrant destroy --force 命令。

為指定專案安裝 Homestead

全域性安裝 Homestead 將會使每個專案共享同一個 Homestead 盒子，你還可以為每個專案單獨安裝 Homestead，這樣就會在該專案下建立 Vagrantfile，允許其他人在該專案中執行 vagrant up 命令，在指定專案根目錄下使用 Composer 執行安裝命令如下：

composer require laravel/homestead --dev

這樣就在專案中安裝了 Homestead。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，可以新增 mariadb 配置項到 Homestead.yaml 檔案，該選項會移除 MySQL 並安裝 MariaDB，MariaDB 是 MySQL 的替代品，完全相容 MySQL，所以在應用資料庫配置中你仍然可以使用 mysql 驅動：

box: laravel/homestead
ip: "192.168.10.10"
memory: 2048
cpus: 4
provider: virtualbox
mariadb: true

安裝 Elasticsearch

要安裝 Elasticsearch，需要新增 elasticsearch 到 Homestead.yaml 檔案並指定一個支援的版本。預設安裝會建立一個名為「homestead」的叢集，不要給 Elasticsearch 分配超過作業系統一半的記憶體，因此確保 Homestead 機器記憶體至少是分配給 Elasticsearch 的兩倍：

box: laravel/homestead
ip: "192.168.10.10"
memory: 4096
cpus: 4
provider: virtualbox
elasticsearch: 6

注：檢視 Elasticsearch 文件學習如何自定義配置。

別名

你可以在 Homestead 目錄下通過編輯 aliases 檔案為 Homestead 機器新增 Bash 別名：

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

更新完 aliases 檔案後，需要通過 vagrant reload --provision 命令重啟 Homestead 機器，以確保新的別名在機器上生效。

日常使用

全域性訪問 Homestead

要想在檔案系統的任意路徑都能夠執行 vagrant up 啟動 Homestead 虛擬機器，在 Mac/Linux 系統中，可以新增 Bash函式到 ~/.bash_profile；在 Windows 系統上，需要新增“批處理”檔案到 PATH。這些指令碼允許你在系統的任意位置執行 Vagrant 命令，並且把命令執行位置指向 Homestead 的安裝路徑。

Mac/Linux

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

確保將該函式中的 ~/Homestead 路徑調整為指向實際的 Homestead 安裝路徑。這樣你就可以在系統的任意位置執行 homestead up 或 homestead ssh 來啟動/登入虛擬機器：

補充知識點：/etc/profile 和 ~/.bash_profile 都可以用來設定系統 PATH，不同之處在於前者是給系統超級使用者使用，後者是給普通登入使用者使用的，此外要讓 ~/.bash_profile 修改後生效，有兩種方法，一種是退出系統重新登入，一種是使用 source ~/.bash_profile 命令。

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，也可以在任意路徑下通過 homestead ssh 登入到虛擬機器。

如果你需要以更簡捷的方式連線到 Homestead，可以為主機新增一個別名來快速連線到 Homestead 盒子，建立完別名後，可以使用 vm 命令從任何地方以 SSH 方式連線到 Homestead 虛擬機器：

alias vm="ssh [email protected] -p 2222"

連線到資料庫

Homestead 預設已經在虛擬機器中為 MySQL 和 Postgres 資料庫做好了配置，更方便的是，這些配置值與 Laravel 的 .env 中預設提供的配置一致。

想要通過本地的 Navicat 或 Sequel Pro 連線到 Homestead 上的 MySQL 或 Postgres 資料庫，可以通過新建連線來實現，主機 IP 都是 127.0.0.1，對於 MySQL 而言，埠號是 33060，對 Postgres 而言，埠號是 54320，使用者名稱/密碼是 homestead/secret：



注：只有從本地連線 Homestead 的資料庫時才能使用這些非標準的埠，在 Homestead 虛擬機器中還是應該使用預設的 3306 和 5432 埠進行資料庫連線配置。

新增更多站點

Homestead 虛擬機器在執行時，可能需要新增多個 Laravel 應用到 Nginx 站點。如果是在單個 Homestead 環境中執行多個 Laravel 應用，新增站點很簡單，只需將站點新增到 Homestead.yaml 檔案，然後在 Homestead 目錄中執行 vagrant provision 命令即可：

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

如果 Vagrant 不是自動管理“hosts”檔案，仍然需要新增站點域名到本地 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、laravel（預設）、proxy、silverstripe、statamic、symfony2 和 symfony4。

站點引數

你也可以通過站點指令 params 新增額外的 Nginx fastcgi_param 值。例如我們可以新增一個 FOO 引數，對應引數值是 BAR：

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.app
      to: /home/vagrant/Code/Laravel/public
      schedule: true

該站點的 Cron 任務會被定義在虛擬機器的 /etc/cron.d 目錄下：



配置 Maillog

通過 Maillog 可以輕鬆攔截髮送出去的郵件並進行檢查而不必真的將其傳送給接收人。開始之前，需要更新 .env 檔案使用如下郵件配置：

MAIL_DRIVER=smtp
MAIL_HOST=localhost
MAIL_PORT=1025
MAIL_USERNAME=null
MAIL_PASSWORD=null
MAIL_ENCRYPTION=null

埠轉發配置

預設情況下，Homestead 埠轉發配置如下：

• SSH: 2222 → Forwards To 22
• ngrok UI: 4040 → Forwards To 4040
• 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 盒子新增更多埠轉發，做如下轉發協議設定即可：

ports:
    - send: 50000
      to: 5000
    - send: 7777
      to: 777
      protocol: udp

分享你的環境

有時候你可能希望和同事或客戶分享自己當前的工作進度或成果，Vagrant 本身支援通過 vagrant share 來支援這個功能；不過，如果你在 Homestead.yaml 檔案中配置了多個站點的話就不行了。

為了解決這個問題，Homestead 內建了自己的 share 命令，該功能實現的原理是通過 Ngrok將本地服務分享到網際網路上進行公開訪問，關於該軟體的細節我們這裡不討論，大家可以自行百度，我們主要關注在 Homestead 中如何使用這一功能。首先通過 vagrant ssh 登入到 Homestead 虛擬機器然後執行 share homestead.test 命令，這樣就可以分享 homestead.test 站點了，其他站點分享以此類推：

share homestead.test

執行完該命令之後，你就可以看到一個 Ngrok 介面出現，其中包含活動日誌和分享站點所需的公開訪問 URL：



可以看到我的分享 URL 是 http://95920d84.ngrok.io/ 以及 https://95920d84.ngrok.io/，你可以通過這兩個域名在任意聯網機器上訪問我的 Homestead 站點：

如果你想要指定一個自定義的區域，子域名或者其他 Ngrok 執行時選項，可以將它們新增到 share 命令：

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

目前自定義域名只有付費使用者才可以使用，所以 subdomain 會提示不可用。

注：記住兩個點，一個是 Vagrant 並沒有什麼特別的安全防範措施，另一個是當你執行 share 命令的時候，你其實是在將自己的虛擬機器曝光到網際網路上。所以，當你要分享自己的站點之前，先想想安全隱患，並將其規避掉。

多個 PHP 版本

注：該功能只在 Nginx 下有效。

Homestead 6 引入了在單個虛擬機器中支援多個 PHP 版本的功能，你可以在 Homestead.yaml 檔案中為特定站點指定 PHP 版本，目前支援的 PHP 版本包括 5.6、7.0 和 7.1 和 7.2：

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

該功能實現的原理是通過 Homestead.yaml 中配置的 PHP 版本在 Homestead 中啟動相應的 php-fpm 服務，然後更新 Nginx 中相應的站點配置：



此外，你可以在 CLI 中使用任意版本的 PHP：

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

Web 伺服器

Homestead 使用 Nginx 作為預設 Web 伺服器。不過，如果指定 apache 作為站點型別，也會安裝 Apache。兩個 Web 伺服器可以同時安裝，但是不能同時執行。Shell 命令 flip 可用於簡化在不同 Web 伺服器之間的切換處理，其工作原理是先自動判斷哪個 Web 伺服器正在執行，然後將其關閉，接著啟動另一個伺服器。要使用這個命令，需要 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 盒子：

vagrant box update

接下來，需要更新 Homestead 原始碼，如果你是通過 Github 倉庫安裝的，只需在克隆倉庫的地方執行 git pull origin master 即可。

如果你是通過專案的 composer.json 檔案安裝的 Homestead，需要確保 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