Laravel Homestead踩坑記1——安裝

以下內容是基於 Homestead |《Laravel 6 中文文件 6.x》| Laravel China 社群 ，該中文教程翻譯至官方文件 。

由於該文件好多內容對於新手來說很難消化，比如我這個新人，為了讓自己以後重灌的時候不會再踩到這麼多坑，因此我準備寫幾篇《踩坑記》。這篇文章不僅可以防踩坑，更重要的是，也可以當作新手的入門教程，即使很多技術我可能解釋的沒那麼專業或者有錯誤，但大多數是為了更容易讓新手理解其含義，技術方面我也不會挖的太深入，以防誤人子弟。

使用的 windows 系統，mac 的繞道~

-用 php 做後端

PHP 後端整合有很多方法，比如採用 wampserver、xampp 等工具傻瓜式整合，但這些工具只是整合了 php + web 伺服器+資料庫，程式碼方面還得自己手動寫個框架（比如 MVC 模式）來接收響應請求。但手動肯定有很多事情要做，還可能因自身技術不大行，很難去更嚴謹、更有保證的去實現自己需要的功能。

因此可以使用別人已經寫好的 laravel 、 thinkphp 等後端框架進行開發。但是這些框架並非像前面的整合工具那樣整合那麼多必要工具，框架中並不包含 php、web 伺服器等，也就是直接使用 laravel 框架需要一些條件，條件就是需要手動整合許多依賴工具，還要手動進行大量的配置，這樣的話部署環境就變得格外的繁瑣了。所以我們就直接使用官方預封裝的 Homestead （Laravel Homestead）來更簡單的部署環境。

但發現 Homestead 坑太多了。。。

-什麼是虛擬機器？

常見的電腦系統有 windows、Linux 等系統。通常在 windows 上裝完 linux 後，兩個系統在一臺電腦上一次只能啟動一個系統：啟動 windows 就要把 linux 關閉，啟動 linux 就要把 windows 關閉。在 windows 中下載一個虛擬機器，把 linux 安裝到虛擬機器中，便可以實現在啟動 windows 時，同時啟動 linux，這樣就實現了在 windows 系統中操作虛擬機器中的 linux 系統，而且還可以使兩套系統完全分離，誰也不會主動影響誰。

-Homestead 預封裝了一個虛擬機器——Homestead Vagrant Box（HVB）

你在網上看到的各種名稱，比如 Homestead 虛擬機器、Homestead Vagrant Box、HVB（我自起的簡寫）、Vagrant Box、virtualbox.box（和 virtualbox 不是一個東西，下面解釋）、homestead.box 等這些名稱的含義都相同，不要搞混了！官方的說法叫 “ Homestead Vagrant Box ” 。

該虛擬機器內建 Ubuntu 作業系統，而該作業系統中內建了 PHP、web 伺服器、mysql 和其他工具軟體。這意味著我們無需在當前使用的 windows 系統下安裝這些軟體，整個開發環境全在 Homestead 虛擬機器（Homestead Vagrant Box）當中！沒錯，你手中的 mysql、php 意義上完全可以解除安裝，為什麼呢？因為在 windows 中寫 php 程式碼，在 Ubuntu 系統中執行！環境全在 Ubuntu 系統中，windows 中直接寫文字都行。

-虛擬機器 與 Vagrant 虛擬機器管理工具

virtualbox 是一個虛擬機器軟體（其他的虛擬機器軟體還有 hyperv 等），注意它是軟體，不是虛擬機器！它可以用來建立多個虛擬機器，當然也可以用來——管理它建立的虛擬機器。

下面的內容講的都是 Homestead Vagrant Box 虛擬機器注入到 virtualbox 虛擬機器軟體中的故事。

Vagrant 是一個虛擬機器管理工具。通俗來講的話，和 virtualbox、hyperv 等虛擬機器軟體的區別在於，Vagrant 在虛擬機器軟體的管理上套了一層管理，它可以同時對 virtualbox 、hyperv 等多個虛擬機器軟體建立的多個虛擬機器進行管理，可以更靈活的管理多個虛擬機器軟體建立的多個虛擬機器。

Vagrant 可以同時對 hyperv、 parallels、virtualbox、vmware_desktop 虛擬機器軟體進行管理。

-安裝 Homestead Vagrant Box 虛擬機器（HVB）

正向理解：在 VirtualBox 虛擬機器軟體 中新增 HVB 虛擬機器 ，利用 Vagrant 工具進行管理。
實際操作：利用 Vagrant 管理工具，將 HVB 虛擬機器 注入到 VirtualBox 虛擬機器軟體中。

由上可知，我們需要安裝的東西有：

1. VirtualBox，VMWare，Parallels ， Hyper-V 選擇一個。這裡選擇 VirtualBox。

2. Vagrant 虛擬機器管理軟體。

3. Homestead Vagrant Box 虛擬機器。

4. homestead 配置程式碼。

最好在某個盤下新建個名為 homestead 的資料夾集中存放，以下面目錄為例：

• - D:\homestead
          |— virtualbox
          |— vagrant
          |— homestead_vagrant_box
          |— homestead   (配置程式碼資料夾)

我們按照【實際操作】順序來進行安裝:

1. VirtualBox 和 Vagrant 記憶體小，直接在官網上下，大多數不會出現網路問題。

2. 注入 HVB 虛擬機器 （近 2G 大小）就比較麻煩了，待下面繼續說明。

小竅門：在某個目錄下的位址列輸入 cmd 再按Enter鍵，cmd 會直接進入該目錄，省去了手打的煩惱~

-安裝 Homestead Vagrant Box 虛擬機器

方法一：

官方使用的方法。
該方法可以直接將 Homestead Vagrant Box 虛擬機器 下載並注入到 Vagrant 中，注入過程會自動進行相關配置。但會發現下載速度特別慢！而且檔案大小有近 2 個 G，所以該方法不可行。若可以下載成功，恭喜你避過這個坑，直接看官方教程去了。當然也可以繼續往下看。

// D:\homestead\homestead_vagrant_box 目錄下
$ vagrant box add laravel/homestead

方法二：

該方法需要手動做一些配置。
這裡是和容易出問題的地方，很多人就是因這個坑而放棄使用 Homestead ，選擇了使用 整合工具 (如 wampserver) + laravel 進行手動配置。但畢竟官方說：強烈推薦你使用 Homestead 做為你的開發環境。

1. 命令列輸入【方法一】的命令，會發現一個 URL 連結，該 URL 即 Homestead Vagrant Box 虛擬機器 版本的網站，但進入該網站發現無論點什麼都沒法下載 近 2G 的 Homestead Vagrant Box 虛擬機器。

   • 該網站顯示 virtualbox 大小 1.66G，這並不是 virtualbox 的大小，而是 Homestead Vagrant Box 虛擬機器的大小，virtualbox 我們在前面已經下載了。
   • virtualbox 是一個虛擬機器軟體，HVB 虛擬機器要注入到 virtualbox 虛擬機器軟體中，HVB 只是 virtualbox 中的一個“box”。
     

2. 我們再輸入 3 後（輸入 3 後按Enter鍵立即 ctrl+c 結束，不然它會自動下載），會發現這個網址：vagrantcloud.com/laravel/boxes/hom...
   
   沒錯，這個網址就是正在下載的連結，我們可以把該網址的版本 10.1.1 改成 Homestead Vagrant Box 虛擬機器 版本的網站 裡的最新版本，將該連結複製給迅雷或其他下載軟體下載。

注意：這裡只是下載了 HVB 虛擬機器，並未將其注入到 virtualbox 虛擬機器軟體中。

• 下載到該目錄下：D:\homestead\homestead_vagrant_box
• 若該版本用迅雷啥的下載的也非常慢，甚至下載速度 0m/s 的話，就先換個版本比較接近的版本下載，並切記往下繼續閱讀！版本方面也是有要求的！

-克隆 Homestead 環境所需要的配置程式碼

// 在 D:/homestead/homestead 目錄中
$ git clone https://github.com/laravel/homestead.git

額…發現 homestead 整體目錄結構是這樣的，多了一層 homestead：

• — D:\homestead
          |—virtualbox
          |—vagrant
          |—homestead_vagrant_box
          |—homestead
                |—homestead
                      |—bin

可以將 D:\homestead\homestead 資料夾 及其剛 clone 的刪除掉，再重新：

在 D:/homestead 目錄中
$ git clone https://github.com/laravel/homestead.git

這麼多餘的一步是為了什麼？雖然有教程引導你，但是踩的坑越多，經驗積累的就越多，有些坑在含糊不定的時候，就是需要這麼大膽的踩！

以上所有初步需要的，都已經下載完成了。

-啟動 Vagrant

在這之前必然是需要某些配置，若不配置，必然會出現很多問題，以上內容顯然沒有進行任何配置，但這並無礙。 我們現在就直接啟動，慢慢一步步的排查問題！

1. 啟動：

   // 在 D:\homestead\homestead 目錄中
   $ vagrant up
   Homestead settings file not found in D:/homestead/homestead

   提示 not found，這是因為我們還未對 homestead 環境進行初始化。

2. init：

   // 在 D:\homestead\homestead 目錄中
   $ init.bat
   Homestead initialized!

3. 重新啟動 Vagrant 後：

   // 在 D:\homestead\homestead 目錄中
   $ vagrant up
   Bringing machine 'homestead' up with 'virtualbox' provider...
   ==> homestead: Box 'laravel/homestead' could not be found. Attempting to find and install...
   homestead: Box Provider: virtualbox
   homestead: Box Version: ~> 9
   ==> homestead: Loading metadata for box 'laravel/homestead'
   homestead: URL: https://vagrantcloud.com/laravel/homestead
   ==> homestead: Adding box 'laravel/homestead' (v9.7.2) for provider: virtualbox
   homestead: Downloading: https://vagrantcloud.com/laravel/boxes/homestead/versions/9.7.2/providers/virtualbox.box
   ==> homestead: Box download is resuming from prior download progress
   Progress: 0% (Rate: 0\*/s, Estimated time remaining: --:--:--)

   提示 Box 'laravel/homestead' could not be found 後，自動在下載某個東西。

意思是要求的 Homestead Vagrant Box 虛擬機器 版本必須>9，因為未找到（not be found）對應版本的虛擬機器，所以自動給你下載對應版本的虛擬機器。咦，我在前面下載的虛擬機器明明是 10.1.1 版本的呀！

命令列輸入 vagrant box list，可以檢視 vagrant 注入了哪些虛擬機器：

// 在 D:\homestead\homestead 目錄中
$ vagrant box list
There are no installed boxes! Use `vagrant box add` to add some.

我們只是下載了 Homestead Vagrant Box 虛擬機器，並沒有讓它注入到 vagrant 中！

-將 Homestead Vagrant Box 虛擬機器 注入 Vagrant 中

很多人採用網上的辦法，比如直接注入（該方法不推薦）：

$ vagrant box add laravel/homestead D:\homestead\homestead_vagrant_box\virtualbox.box

這樣的雖然注入成功，但是還是無法啟動 Vagrant ，還是顯示上面的相同結果（not be found.），並且我們發現注入的 Homestead Vagrant Box 虛擬機器 版本是 0，顯然不滿足版本必須>9：

$ vagrant box list
laravel/homestead (virtualbox, 0)

如果你操作了這一步，可以輸入下面命令將該注入進行刪除：

// 在 D:\homestead\homestead 目錄中
$ vagrant box remove laravel/homestead --box-version 0
// 刪除成功。

//若版本不是 0，而是 5.1.1 這樣的，那麼把 0 改成對應的版本即可刪除，比如：
$ vagrant box list
laravel/homestead (virtualbox, 5.1.1)
$ vagrant box remove laravel/homestead --box-version 5.1.1
// 刪除成功。
$ vagrant box list
There are no installed boxes! Use `vagrant box add` to add some.

那麼問題來了，下載的虛擬機器明明是 10.1.1 版本，為什麼是 0？

這是因為該虛擬機器是手動注入的（上面的【方法一】是自動注入、自動配置的），手動注入的虛擬機器並不會自動配置後設資料（裡面包含版本資訊），在預設情況下會識別版本為 0。

推薦採用下面的方法：

1. 我們需要在 D:\homestead\homestead_vagrant_box 目錄下新建一個名為 metadata.json 的檔案進行後設資料配置，內容如下：

   {
   "name": "laravel/homestead",
   "versions":
   [
       {
           "version": "10.1.1",
           "providers": [
               {
                 "name": "virtualbox",
                 "url": "D:/homestead/homestead_vagrant_box/virtualbox.box"
               }
           ]
       }
   ]
   }

   欄位說明：
   “version”：你所使用的 Homestead Vagrant Box 虛擬機器 的版本。
   “url”：你所使用的 Homestead Vagrant Box 虛擬機器 的路徑(絕對相對都可)。

2. 將後設資料注入到 Vagrant 中

   // 在 D:\homestead\homestead_vagrant_box 目錄下
   $ vagrant box add metadata.json
   .
   .
   .
   ==> box: Successfully added box 'laravel/homestead' (v10.1.1) for 'virtualbox'!

   $ vagrant box list
   laravel/homestead (virtualbox, 10.1.1)

   注入後設資料時，會同時注入後設資料所配置的對應 HVB（virtualbox.box）。

3. 再次啟動 Vagrant，發現還是這個問題could not be found：

   // 在 D:\homestead\homestead 目錄下
   $ vagrant up
   Bringing machine 'homestead' up with 'virtualbox' provider...
   ==> homestead: Box 'laravel/homestead' could not be found. Attempting to find and install...
   homestead: Box Provider: virtualbox
   homestead: Box Version: ~> 9
   ==> homestead: Loading metadata for box 'laravel/homestead'
   homestead: URL: https://vagrantcloud.com/laravel/homestead
   ==> homestead: Adding box 'laravel/homestead' (v9.7.2) for provider: virtualbox

   這是因為需要版本對應！詳細的可以檢視這篇文章 解決 Homestead 版本與 homestead.box 不對應造成的衝突 。

   文章裡的裡 homestead.box 即 Homestead Vagrant Box 虛擬機器。

   簡而言之就是，當前 homestead 環境版本（clone 過來的配置程式碼版本）必須使用指定版本的 Homestead Vagrant Box 虛擬機器！而我當前使用的 homestead 環境版本 是 10.17.0，看 github 上的文件說明需要使用的是 Homestead Vagrant Box v9.7.2，而這裡使用的是 Homestead Vagrant Box v10.1.1。

   

   同樣在上面的命令列當中能看到如果”not be found“的話，會繼續自動下載指定的 v9.7.2 版本（下載的非常慢）：

   ==> homestead: Adding box 'laravel/homestead' (v9.7.2) for provider: virtualbox

4. 下載對應適配的版本（我這裡是 9.7.2）：

   把這個網址版本數字改成指定版本，複製給迅雷下載: vagrantcloud.com/laravel/boxes/hom...

   1. 由於一些版本哪怕用迅雷下載，下載速度也是極慢，因此我們可能無法將要求的指定版本的 HVB 下載成功。

   2. 經過我的測試，根據下面情況進行版本的選擇，暫時並沒有出現過什麼問題：

      • 下載的 HVB 版本，必須大於 Homestead 版本 所指定的版本（要求是 9.7.2），下載 10.X.X 版本的 HVB 也可以；

      • 後設資料所配置的版本“version”，首先必須大於 Homestead 版本 所指定的版本（要求是 9.7.2），其次必須限制在 9.X.X 版本上，不能越界為 10.X.X！

5. 刪除 10.1.1 版本的虛擬機器：

   // 在 D:\homestead\homestead 目錄下
   $ vagrant box list
   laravel/homestead (virtualbox, 10.1.1)
   $ vagrant box remove laravel/homestead --box-version 10.0.1

6. 把後設資料中的 “version” 改成 9.7.2，”url”改成新下載的 HVB 路徑，並重覆上面步驟：

   // 在 D:\homestead\homestead_vagrant_box 目錄中
   $ vagrant box add metadata.json
   ==> box: Loading metadata for box 'metadata.json'
   box: URL: file://D:/homestead/homestead_vagrant_box/metadata.json
   ==> box: Adding box 'laravel/homestead' (v9.7.2) for provider: virtualbox
   box: Downloading: D:/homestead/homestead_vagrant_box/virtualbox.box
   box:
   ==> box: Successfully added box 'laravel/homestead' (v9.7.2) for 'virtualbox'!

啟動 Vagrant 時，若顯示以下資訊，有多個方法解決：

// 在 D:\homestead\homestead 目錄中
$ Vagrant up
Bringing machine 'homestead' up with 'virtualbox' provider...
==> homestead: Importing base box 'laravel/homestead'...
==> homestead: Matching MAC address for NAT networking...
==> homestead: Checking if box 'laravel/homestead' version '9.7.2' is up to date...
A VirtualBox machine with the name 'homestead' already exists.
Please use another name or delete the machine with the existing
name, and try again.

這是因為名叫homestead的虛擬機器已經被啟動，即使已經被remove，
我們可以開啟虛擬機器軟體刪除它，刪除前先退出-關閉電源：

在重新啟動 Vagrant ，顯示更長一段內容，沒有顯示錯誤，直到執行結束，則代表成功：

// 在 D:\homestead\homestead 目錄中
$ Vagrant up
Bringing machine 'homestead' up with 'virtualbox' provider...
==> homestead: Checking if box 'laravel/homestead' version '9.7.2' is up to date...
==> homestead: Setting the name of the VM: homestead
==> homestead: Clearing any previously set network interfaces...
==> homestead: Preparing network interfaces based on configuration...
homestead: Adapter 1: nat
homestead: Adapter 2: hostonly
==> homestead: Forwarding ports...

開啟 虛擬機器軟體 ，可以看到虛擬機器正在執行，我們便可以開始建立專案了：

-vagrant 命令

1. vargrant up：啟動 HVB，若未安裝 HVB ，則會自動下載並安裝。
2. vargrant destroy：銷燬 HVB，並銷燬 HVB 中的一切，比如 composer 安裝包、mysql軟體及 mysql 全部資料（當然可以備份） 等。但是你建立的專案仍保留著。
3. vagrant reload：重啟虛擬機器。
4. vagrant provision：重新載入 Homestead 配置。
5. vagrant reload -provision：重啟虛擬機器，並重新載入 Homestead 配置。

-修改 HVB 虛擬機器安裝位置：

在【全域性設定】中可以把 HVB 安裝的位置修改了，預設在C盤，這肯定是不好的，一個虛擬機器初始化安裝就能達 6G 儲存大小，這C盤可消耗不來。

另外，若想遷移當前已建立的 HVB ，就得需要配置很多雜碎的東西，似乎挺麻煩的，所以還是建議 vagrant destroy 後再 vagrant up ，重建一個 HVB，不過

再次提醒一下，這裡的 HVB 只是 VirtualBox 的一個 box 而已。

本篇結束，謝謝閱讀。

本作品採用《CC 協議》，轉載必須註明作者和本文連結