Homestead · Laravel 5.6 中文文檔

* * * * * [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 任務](http://www.hmoore.net/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 ~~~