將 Laravel 開發環境由 Homestead 遷移到 Laravel Sail ( Docker ) 完整詳細教程

myhui0926發表於2021-05-10
Laravel開發環境AIDocker

微軟的 wsl2 隨著 Windows10 20H1 版本一同釋出了，跟 wsl1 相比，wsl2 擁有了完整的 Linux 核心。基於 wsl2 執行的 Docker 可以得到原生 Linux 下的體驗。

附：比較wsl1和wsl2

我有一個基於 Dcat Admin 開發的管理後臺，將開發環境遷移到 Laravel Sail( Docker ) 後，開啟頁面的速度快了很多倍，再也沒有之前的卡頓感了（相信用過 Homestead 開發專案的小夥伴深有體會）。因虛擬機器與宿主機之間羸弱的跨 OS 檔案效能，導致 Homestead 中執行的專案在宿主機瀏覽器開啟時，給人的感覺總是很卡。而且每次啟動 Homestead 耗時也很長，每次 coding 前，光開啟 Homestead 這個「重量級」開發環境，就讓人頭疼。然而使用 Laravel Sail 後，幾秒鐘就能啟動 Docker 容器，馬上就能投入開發。即使是在膝上型電腦上，Laravel Sail 也顯得特別輕量，風扇不再像之前那樣狂轉了。是時候將我們的開發環境由「卡慢」的 Homestead 遷移到Docker下了。

注意：擺脫卡頓感的前提是專案程式碼放在linux子系統中，而不是放在宿主機上。IDE或編輯器通過網路位置來開啟專案，後面我會介紹。教程《搭建 Laravel Sail 開發環境 - Windows》中將專案程式碼放在 /mnt/c/code 或 /mnt/d/code 這樣的宿主機目錄中，我認為是不恰當的，因為wsl2是執行在虛擬機器中的，所以 wsl2 跨 OS 檔案系統的效能同樣很差。將程式碼放到宿主機目錄，你的專案執行速度跟 Homestead 中執行一樣卡。

雖然Laravel China 釋出的《搭建 Laravel Sail 開發環境 - Windows》中介紹了基於 Laravel Sail 的開發環境搭建，但教程是基於建立一個新專案的實踐來進行。該教程是通過執行以下指令碼來構建新專案的：

curl -s https://laravel.build/example-app | bash

但是執行該命令由於要預先構建一個「先導映象」，再加上國內的網路問題，導致非常耗時而且非常容易安裝失敗。所以我自己在實踐中總結出了一條可行的方法，現在分享給大家。

基礎環境要求主要有以下幾點：

  • windows 作業系統版本要達到要求
  • 開啟 Hyperf-v 和 wsl2
  • 安裝實用工具 Windows Terminal 和 Visual Studio Code
  • 安裝 Ubuntu 子系統
  • 安裝 Docker Desktop 並讓 Docker Desktop 基於 wsl2 來執行
    基礎環境準備可以完全參照《搭建 Laravel Sail 開發環境 - Windows》來進行，我跟教程作者不同的是「六、建立測試專案 」及後面的部分，前面的部分都可以參照教程來進行。基礎環境準備方面我們就簡單的走一遍流程。

    windows作業系統版本

    執行 winver 命令檢視 Windows 版本，你的 Windows 版本不能低於 20H2 版本。

將 Laravel 開發環境由 Homestead 遷移到 Laravel Sail（ Docker ）

如果你的作業系統版本較低，可以使用 Windows 更新或者「微軟易升」來升級你的作業系統。而且我測試過了 Windows10 家庭版也可以滿足環境要求，不需要花錢升級到專業版。

啟用hyperf-v和wsl2

點選win10左下角的搜尋按鈕，輸入「功能」，開啟「 windows 功能」介面：

將Laravel開發環境由Homestead遷移到Docker（基於Laravel Sail，win10 作業系統）

開啟以下功能：「適用於 Linux 的 Windows 子系統」、「虛擬機器平臺」、「Hyperf-v」（可選，當個虛擬機器軟體用）三項功能。Windows 家庭版沒有「Hyperf-v」，不需要開啟，不影響開發環境的搭建。等待電腦重啟後，就安裝好了。

安裝實用工具

  • Windows 應用商店搜尋安裝 Windows Terminal；
  • 安裝Visual Studio Code。
    這裡就不再贅述

安裝 Ubuntu 子系統

Windows 應用商店搜尋 Ubuntu，選擇安裝 Ubuntu 或者 Ubuntu 20.04LTS，兩者二選一即可：

將Laravel開發環境由Homestead遷移到Docker（基於Laravel Sail，win10 作業系統）

點選開始選單 Ubuntu 圖示，啟動 Ubuntu，按照提示設定使用者名稱、密碼，同時請記住自己設定的使用者名稱和密碼。啟動中如果遇到問題，請使用搜尋引擎搜尋，一般都有解決方案。

附： 使用 WSL2 出現“參考的物件型別不支援嘗試的操作”解決辦法:

開啟 Windows Terminal( shell 工具選擇 Powershell)，將 wsl2 設為預設的 Linux 子系統環境：

wsl --set-default-version 2

執行以下命令，檢視相關應用執行的 wsl 版本：

 wsl --list --verbose

執行結果如下：

將 Laravel 開發環境由 Homestead 遷移到 Laravel Sail ( Docker ) 完整詳細教程

請確保你的 Ubuntu-20.04 是執行的 wsl 版本為 2,如果你的版本為1，請執行以下命令切換：

wsl --set-version Ubuntu-20.04 2

安裝 Docker Desktop

到 Docker 官網下載安裝 Docker Desktop，安裝完成後，開啟 Docker，開啟 WSL2 ：

開啟 WSL2

與 Ubuntu 進行整合：

與 Ubuntu 進行整合

如果沒看到Ubuntu選項，檢視部落格文章《搭建 Laravel Sail 開發環境 - Windows,docker選項設定 沒有 ‘ubuntu’選項》來解決。

接下來配置 Docker Hub 映象加速，按下圖開啟 Docker Desktop 配置介面:

配置 Docker Hub 映象加速

將映象加速的配置貼上到相應位置：

"registry-mirrors": [
    "https://mirror.baidubce.com",
    "https://hub-mirror.c.163.com",
    "https://docker.mirrors.ustc.edu.cn"
  ],

如果需要阿里雲的映象加速地址，需要自己去註冊一個阿里雲賬號，每個人的加速地址都不一樣。

登入阿里雲後點選控制檯，按照下圖指示找到映象加速地址：
申請阿里雲的映象加速地址
申請阿里雲的映象加速地址

至此，基礎的軟體工具都安裝配置好了，後面部分跟《搭建 Laravel Sail 開發環境 - Windows》有所不同。

在使用 Laravel Sail 前，我們需要先通過 Composer 來安裝它，所以需要基礎的 PHP 執行環境。

在 Windows Terminal 中啟動 Ubuntu

在 Windows Terminal 中啟動 Ubuntu

Ubuntu 更換國內源加速

備份原來的源：

sudo cp /etc/apt/sources.list sources.list.bak

使用 vim 編輯 sources.list 檔案，替換為以下內容：

deb http://mirrors.aliyun.com/ubuntu/ focal main restricted universe multiverse

deb http://mirrors.aliyun.com/ubuntu/ focal-security main restricted universe multiverse

deb http://mirrors.aliyun.com/ubuntu/ focal-updates main restricted universe multiverse

deb http://mirrors.aliyun.com/ubuntu/ focal-proposed main restricted universe multiverse

deb http://mirrors.aliyun.com/ubuntu/ focal-backports main restricted universe multiverse

deb-src http://mirrors.aliyun.com/ubuntu/ focal main restricted universe multiverse

deb-src http://mirrors.aliyun.com/ubuntu/ focal-security main restricted universe multiverse

deb-src http://mirrors.aliyun.com/ubuntu/ focal-updates main restricted universe multiverse

deb-src http://mirrors.aliyun.com/ubuntu/ focal-proposed main restricted universe multiverse

deb-src http://mirrors.aliyun.com/ubuntu/ focal-backports main restricted universe multiverse

新增PPA源

sudo sh -c "echo 'deb https://launchpad.proxy.ustclug.org/ondrej/php/ubuntu focal main'  > /etc/apt/sources.list.d/ppa_ondrej_php.list"

更新資源列表

sudo apt update

然後會產生以下錯誤：

W: GPG error: launchpad.proxy.ustclug.org/ondrej... focal InRelease: The following signatures couldn’t be verified because the public key is not available: NO_PUBKEY 4F4EA0AAE5267A6C
E: The repository ‘launchpad.proxy.ustclug.org/ondrej... focal InRelease’ is not signed.
N: Updating from such a repository can’t be done securely, and is therefore disabled by default.
N: See apt-secure(8) manpage for repository creation and user configuration details.

GPG error

執行以下命令匯入你的公鑰即可( 4F4E...7A6C 這一串公鑰要換成你自己螢幕上輸出的那個)：

sudo apt-key adv --keyserver keyserver.ubuntu.com --recv-keys 4F4EA0AAE5267A6C

設定成功後，重新更新資源列表:

sudo apt update

安裝php8.0

sudo apt install -y php8.0-cli php8.0-dev php8.0-pgsql php8.0-sqlite3 php8.0-gd php8.0-curl php8.0-memcached php8.0-imap php8.0-mysql php8.0-mbstring php8.0-xml php8.0-zip php8.0-bcmath php8.0-soap php8.0-intl php8.0-readline php8.0-msgpack php8.0-igbinary php8.0-ldap php8.0-redis

安裝php7.4

sudo apt install -y php7.4-cli php7.4-dev php7.4-pgsql php7.4-sqlite3 php7.4-gd php7.4-curl php7.4-memcached php7.4-imap php7.4-mysql php7.4-mbstring php7.4-xml php7.4-zip php7.4-bcmath php7.4-soap php7.4-intl php7.4-readline php7.4-pcov php7.4-msgpack php7.4-igbinary php7.4-ldap php7.4-redis

需要其他版本的PHP請自行安裝。

你會發現我們並沒有安裝 php-fpm ，因為我們要使用 Docker 來構建開發環境，現在的 PHP 環境只要能夠在 CLI 執行環境下執行 Composer 就夠了。當然，由於 WSL2 中的 Ubuntu 擁有完整的核心，你可以直接在 Ubuntu 子系統中安裝 Nginx , php-fpm, Mysql, Redis等，包括 swoole 擴充套件， 可以直接基於 Ubuntu 子系統來構建開發環境。這裡我們就不再贅述。

切換PHP版本

由於很多擴充套件目前還不支援 PHP8.0，所以我們也同時安裝了 PHP7.4 版本。很多時候我們需要切換不同版本的 PHP，通過以下命令來切換 PHP 版本：

  1. 切換 cli 執行模式下預設的 PHP 版本
    sudo update-alternatives --config php
    輸入對應PHP版本的數字，完成切換：
    輸入相對應PHP版本的數字

  1. 切換 phpize 版本：

    sudo update-alternatives --config phpize

  2. 切換 php-config 版本

    sudo update-alternatives --config php-config

  3. 確認現在的PHP版本：

    php -v

安裝 Composer

複製以下命令貼上到 Ubuntu 子系統中執行，以安裝 composer ，並將 composer 映象配置為阿里雲映象：

sudo sh -c "curl -so /usr/bin/composer https://mirrors.aliyun.com/composer/composer.phar && chmod a+x /usr/bin/composer" \
&& composer --version \
&& composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/ \
&& composer config -g -l | grep repositories.packagist.org.url

如果控制視窗顯示出了 Composer 版本和映象源地址，說明安裝成功了：
將 Laravel 開發環境由 Homestead 遷移到 Laravel Sail ( Docker ) 完整詳細教程

至此，我們的PHP基礎環境就安裝好了。

建立專案目錄

進入你的 Ubuntu 子系統的家目錄：

cd ~

注意： 這裡是進入 Ubuntu 子系統的家目錄，而不是Windows10的。

建立一個 projects 目錄，用於存放專案程式碼：

mkdir projects

用 VS Code 開啟家目錄：

code .

這裡要注意，由於 WSL2 跨OS的檔案效能很差，會導致專案執行速度很慢，所以我們的專案目錄是存放在 Ubuntu 子系統中的家目錄， 而不是 windows10 的家目錄。後面呼叫code .命令是為了用 VS Code 開啟我們的projects目錄，以獲取projects目錄的網路位置路徑，方便我們使用諸如phpStorm這樣的IDE開啟專案。

在 VS Code 介面，右鍵projects目錄，選擇Reveal in Explorer，也就是在 Windows檔案管理器 中開啟目錄：
用VS Code開啟projects目錄

在windows資源管理器中，右鍵projects目錄，選擇固定到快速訪問和傳送到 -> 桌面快捷方式，便於以後開啟專案目錄。

建立projects目錄的快捷訪問

所以，即使我們的專案存放在 Ubuntu 子系統中，專案目錄也是可以通過網路位置訪問的，我第一次按照社群官方教程搭建 Laravel Sail 開發環境時，也是將專案存放在/mnt/c/code目錄下，這就產生了跨OS的檔案系統效能問題，專案的執行速度並沒有令我滿意。我也是在無意間在 Windows Terminal 中使用code命令開啟 Ubuntu 子系統中的家目錄時，才發現了可以通過網路位置開啟專案目錄。

將專案存放目錄新增到 Windows Denfender 的白名單中

接下來，為了防止 Windows Defender 因安全原因，可能會阻止 IDE 掃描專案目錄，所以我們將 projects目錄加入 Windows Defender 的白名單中。
在Windows資源管理器中開啟projects目錄，複製projects目錄的路徑：

複製projects目錄的地址

開啟Windows 安全中心, 按下圖所示，開啟病毒和威脅防護設定介面：

微信和防護設定

點選“新增或刪除排除項”，點選“新增排除項”按鈕，選擇“資料夾”，將剛剛複製的projects目錄的路徑新增到排除項中，同時，也可以將你的IDE程式也新增到排除項中（點選“新增排除項”按鈕，選擇“程式”）：
新增projects目錄的路徑到排除項

拉取專案原始碼

回到 Windows Terminal 介面，進入專案存放目錄：

cd /home/myhui/projects

假設我們現在有一個專案，叫做 kkyn_dcat_admin，拉取你的專案原始碼（或者建立新的專案）:

git clone git@gitee.com:kkyn_dcat_admin.git

這裡說明一下，如果你使用ssh協議拉取專案原始碼，由於 Ubuntu 子系統跟 Windows10 宿主系統是隔離的，所以你需要將 windows 10 的 SSH Key 拷貝到 Ubuntu 子系統中（注意不要完全複製貼上，ASUS和myhui要改成你自己的:smiley:。）：

cp /mnt/c/Users/ASUS/.ssh/id_rsa* /home/myhui/.ssh/

如果你還沒有SSH KEY，可以用 Git Bash 重新生成 SSH Key，並將生成的公鑰新增你的github或者gieee信任列表中。生成SSH Key使用命令，郵箱換成你自己的郵件地址:

ssh-keygen -t rsa -C "your_email@example.com

具體步驟 不再贅述。

安裝Laravel Sail

使用 IDE 或者編輯器開啟專案：
開啟專案

編輯composer.json檔案，新增"laravel/sail": "^1.5" 開發依賴：

將 Laravel 開發環境由 Homestead 遷移到 Laravel Sail ( Docker ) 完整詳細教程

回到 Windows Terminal 介面, 開啟 Ubuntu 選項卡，進入你的專案目錄：

cd ~/projects/kkyn_dcat_admin

釋出.env檔案

cp .env.example .env

用IDE編輯.env檔案，配置你的mysql、redis選項：

# mysql
DB_CONNECTION=mysql
DB_HOST=mysql
DB_PORT=3306
DB_DATABASE=kkyn
DB_USERNAME=root
DB_PASSWORD=password

# redis
REDIS_HOST=redis
REDIS_PASSWORD=null
REDIS_PORT=6379
REDIS_CLIENT=phpredis

執行命令安裝依賴：

composer install

注意：我們安裝在 Ubuntu 子系統中的php環境主要用來安裝依賴，如果你不想使用Docker來做開發環境，請自行在 Ubuntu 子系統中安裝諸如mysql、redis等的其他軟體。

釋出 Dockerfile 以便定製

由於國內的網路問題，我們需要對 Dockerfile 進行定製，以獲得更快的構建速度。執行下面的命令，釋出 Dockerfile 檔案

php artisan sail:publish

命令執行完成後，你可以看到專案目錄中，多了一個docker目錄。

定製 Dockerfile

用 IDE 或編輯器開啟 kkyn_dcat_admin/docker/7.4/Dockerfile檔案, 按照以下步驟進行定製。

  1. 在kkyn_dcat_admin/docker/7.4目錄下，建立一個sources.list檔案，將以下內容貼上進去：

    deb http://mirrors.aliyun.com/ubuntu/ focal main restricted universe multiverse
deb-src http://mirrors.aliyun.com/ubuntu/ focal main restricted universe multiverse
deb http://mirrors.aliyun.com/ubuntu/ focal-security main restricted universe multiverse
deb-src http://mirrors.aliyun.com/ubuntu/ focal-security main restricted universe multiverse
deb http://mirrors.aliyun.com/ubuntu/ focal-updates main restricted universe multiverse
deb-src http://mirrors.aliyun.com/ubuntu/ focal-updates main restricted universe multiverse
deb http://mirrors.aliyun.com/ubuntu/ focal-proposed main restricted universe multiverse
deb-src http://mirrors.aliyun.com/ubuntu/ focal-proposed main restricted universe multiverse
deb http://mirrors.aliyun.com/ubuntu/ focal-backports main restricted universe multiverse
deb-src http://mirrors.aliyun.com/ubuntu/ focal-backports main restricted universe multiverse

  2. 配置 Ubuntu 國內映象
    回到Dockerfile檔案，在 RUN ln -snf /usr/share/zoneinfo/$TZ /etc/localtime && echo $TZ > /etc/timezone這句程式碼後面，加入以下程式碼：

    ADD sources.list /etc/apt/

  3. Ubuntu PPA 加速

在Dockerfile檔案中，搜尋：

http://ppa.launchpad.net

將其替換為：

https://launchpad.proxy.ustclug.org
  1. 安裝Composer
    在Dockerfile檔案中，搜尋下面這行程式碼:
     && php -r "readfile('http://getcomposer.org/installer');" | php -- --install-dir=/usr/bin/ --filename=composer \
    將其替換為以下程式碼：
    && curl -so /usr/bin/composer https://mirrors.aliyun.com/composer/composer.phar \
&& chmod a+x /usr/bin/composer \
&& composer --version \
&& composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/ \

釋出docker-compose.yml檔案

php artisan sail:install --with=mysql,redis

with選項可選的值有 mysql, pgsql, mariadb, redis, memcached, meilisearch, mailhog, selenium。自己根據情況選擇。如果執行php artisan sail:install命令不帶--with選項，會出現一個選擇框，選擇需要一同參與編排的映象列表。

定製docker-compose.yml檔案

將 Laravel 開發環境由 Homestead 遷移到 Laravel Sail ( Docker ) 完整詳細教程

其他可定製項包括應用的埠、MySQL的埠等等，根據自己的需求定製。不熟悉 Docker 的朋友請自行學習。

構建映象並啟動容器

使用Windows Terminal，開啟 Ubuntu 標籤頁，通過 Ubuntu 進入你的專案目錄~/projects/kkyn_dcat_admin，執行以下命令：

./vendor/bin/sail up

看到以下介面，說明已經啟動成功了

將 Laravel 開發環境由 Homestead 遷移到 Laravel Sail ( Docker ) 完整詳細教程

通過 Docker Desktop 介面可以看到容器的執行情況：

將 Laravel 開發環境由 Homestead 遷移到 Laravel Sail ( Docker ) 完整詳細教程

生成KEY：

./vendor/bin/sail artisan key:generate

執行資料遷移：

./vendor/bin/sail artisan migrate

注： 如果以上命令不生效，可以進入容器裡面執行命令
進入容器：

docker exec -it kkyn_dcat_admin_kkadmin.test_1 /bin/bash

執行命令：

php artisan key:generate
php artisan migrate

如果你不知道自己的容器名叫什麼，可以執行以下命令檢視：

docker ps -a

見下圖，複製NAMES下對應的容器名，當然，建議你花 1 個小時學一下 Docker：
將 Laravel 開發環境由 Homestead 遷移到 Laravel Sail ( Docker ) 完整詳細教程

編輯 hosts 檔案，配置開發用的域名：

127.0.0.1 example.test

至此，整個Laravel Sail環境就搭建完成了,瀏覽器訪問example.test:

將 Laravel 開發環境由 Homestead 遷移到 Laravel Sail ( Docker ) 完整詳細教程

由於這種搭建方式不存在跨OS的檔案效能問題，所以執行速度比 Homestead 快多了。

開啟 Phpstorm，選擇 File -> Settings -> PHP

注：我這是最新版的 PhpStorm ,老版本的 PhpStorm 位置略有不同。

  1. 配置所依賴的 PHP 版本
    將 Laravel 開發環境由 Homestead 遷移到 Laravel Sail ( Docker ) 完整詳細教程

  2. 配置 PHP CLI 介面
    將 Laravel 開發環境由 Homestead 遷移到 Laravel Sail ( Docker ) 完整詳細教程
    將 Laravel 開發環境由 Homestead 遷移到 Laravel Sail ( Docker ) 完整詳細教程

由於 Ubuntu 子系統有自己的許可權系統，很多時候與宿主機互動會遇到很多檔案許可權問題，所以建議將你的projects目錄許可權改為777:

sudo chmod -R 777 ~/projects/

到這裡我們的教程就結束了，有不完善的地方或者錯誤，歡迎大家指出，我也會在後續的實踐中不斷改進教程。

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

相關文章