使用 PhpStorm 來開發和 Debug Laravel Sail 專案

Laravel Sail 是為 Laravel 提供的基於 Docker 的開發環境，可同時搭建包含 PHP、MySQL、Redis，XDebug 在內的開發環境，優勢：

• 降低開發環境的搭建難度
• 將對主機已有環境的影響降至最低
• 統一團隊開發環境

在 WSL 內使用指令：

curl -s https://laravel.build/<專案名稱> | bash

執行後，將在當前目錄下建立一個 <專案名稱> 的資料夾，並在裡面構建一個 Laravel Sail 專案。

成功建立 Laravel 專案後，我們通過 cd 指令進入專案目錄

cd <專案名稱>

安裝 Laravel Sail 後，不要馬上按照提示執行 vendor/bin/sail up，還需要針對國內網路環境對 Dockerfile 進行調整，也就是將其中 Composer 等包管理工具的包來源修改為國內映象網站。

Laravel Sail 支援使用者自定義 Dockerfile 檔案，只需使用以下指令釋出 Dockerfile 檔案即可

php artisan sail:publish

釋出後，可在專案根目錄的 docker 資料夾中找到對應的 Dockerfile，共有三個版本，具體是哪個版本可開啟專案根目錄的 docker-compose.yml 檢視。

# For more information: https://learnku.com/docs/laravel/sail
version: '3'
services:
    laravel.test:
        build:
            # 此處即為執行的 Dockerfile 所在的資料夾
            context: ./docker/8.1
            # 此處為 Dockerfile 的檔名
            dockerfile: Dockerfile
            # 此處記錄 Dockerfile 的引數，${var} 表示 .env 檔案中 var 對應的值
            args:
                WWWGROUP: '${WWWGROUP}'

找到對應的 Dockerfile 後，將其中的內容替換為：

來源：PRIN BLOG 略有修改

Dockerfile

# FROM  [PRIN BLOG]https://printempw.github.io/laravel-sail-built-with-mirrors/
FROM ubuntu:21.04

LABEL maintainer="Taylor Otwell"

ARG WWWGROUP

# DEBUG ARGUMENT
ARG XDEBUG
ARG XDEBUG_PORT

WORKDIR /var/www/html

ENV DEBIAN_FRONTEND noninteractive
ENV TZ=Asia/Shanghai
ENV APT_MIRROR http://mirrors.ustc.edu.cn
ENV NVM_DIR /usr/local/nvm
ENV NODE_VERSION 16.9.1
ENV NVM_NODEJS_ORG_MIRROR https://mirrors.ustc.edu.cn/node
ENV NVM_SOURCE https://hub.fastgit.org/nvm-sh/nvm.git

SHELL ["/bin/bash", "-o", "pipefail", "-c"]

RUN ln -snf /usr/share/zoneinfo/$TZ /etc/localtime && echo $TZ > /etc/timezone

RUN echo 'APT::Acquire::Retries "5";' > /etc/apt/apt.conf.d/80-retries \
  && sed -i "s|http://archive.ubuntu.com|$APT_MIRROR|g; s|http://security.ubuntu.com|$APT_MIRROR|g" /etc/apt/sources.list \
  && sed -i "s|http://ports.ubuntu.com|$APT_MIRROR|g" /etc/apt/sources.list \
  && apt-get update \
  && apt-get install -y gnupg gosu curl ca-certificates zip unzip

RUN apt-get install -y git supervisor sqlite3 libcap2-bin libpng-dev python2

RUN mkdir -p ~/.gnupg \
  && chmod 600 ~/.gnupg \
  && echo "disable-ipv6" >> ~/.gnupg/dirmngr.conf \
  && apt-key adv --homedir ~/.gnupg --keyserver hkp://keyserver.ubuntu.com:80 --recv-keys E5267A6C \
  && apt-key adv --homedir ~/.gnupg --keyserver hkp://keyserver.ubuntu.com:80 --recv-keys C300EE8C \
  # PHP
  && echo "deb https://launchpad.proxy.ustclug.org/ondrej/php/ubuntu hirsute main" > /etc/apt/sources.list.d/ppa_ondrej_php.list \
  && apt-get update \
  && apt-get 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-pcov \
     php8.0-msgpack php8.0-igbinary php8.0-ldap \
     php8.0-redis php8.0-swoole php8.0-xdebug

  # Composer
RUN 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/ \
  # Node.js
  && mkdir -p $NVM_DIR \
  && curl -so- https://raw.fastgit.org/nvm-sh/nvm/v0.38.0/install.sh | bash \
  && source $NVM_DIR/nvm.sh \
  && nvm install $NODE_VERSION \
  && nvm use $NODE_VERSION \
  && node -v && npm -v \
  && npm config set registry https://registry.npm.taobao.org \
  # Yarn
  && npm install --global yarn \
  && yarn config set registry https://registry.npm.taobao.org \
  && apt-get install -y mysql-client \
  && apt-get install -y postgresql-client \
  && apt-get -y autoremove \
  && apt-get clean \
  && rm -rf /var/lib/apt/lists/* /tmp/* /var/tmp/*

ENV NODE_PATH $NVM_DIR/v$NODE_VERSION/lib/node_modules
ENV PATH $NVM_DIR/versions/node/v$NODE_VERSION/bin:$PATH

RUN setcap "cap_net_bind_service=+ep" /usr/bin/php8.0

RUN groupadd --force -g $WWWGROUP sail
RUN useradd -ms /bin/bash --no-user-group -g $WWWGROUP -u 1337 sail

COPY start-container /usr/local/bin/start-container
COPY supervisord.conf /etc/supervisor/conf.d/supervisord.conf
COPY php.ini /etc/php/8.0/cli/conf.d/99-sail.ini
RUN chmod +x /usr/local/bin/start-container

EXPOSE 8000

ENTRYPOINT ["start-container"]

修改後，即可啟動容器

vendor/bin/sail up

若容器尚未構建的話，該指令會自動構建容器後啟動。也可以使用 -d 引數使其在後臺執行。

vendor/bin/sail up -d

若想要關閉在後臺執行的容器，可以使用指令

vendor/bin/sail stop

如果在此前你已經構建過容器且希望重新構建一個，可以使用以下命令重新構建：

vendor/bin/sail build --no-cache

成功啟動容器後，使用主機訪問 localhost 即可看到 Laravel 的初始介面

如果出現 Permission Denied 的情況，請賦予專案目錄 777 許可權，在專案目錄根目錄下執行

sudo chmod 777 ./ -R

File >> Open 在子系統的目錄中選擇我們的專案

開啟專案後，可以直接在 Terminal 中執行需要在子系統中執行的指令，從而擺脫來回切換 PhpStorm 和 Windows Terminal 的麻煩。

將專案目錄及內其內的檔案許可權修改為 777，方便使用 PhpStorm 進行編輯。

sudo chmod 777 ./ -R 

這樣之後就可以關閉獨立的 WSL 視窗了，直接在 PhpStorm 的 Terminal 視窗啟動即可。

為了能夠使用 Xdebug ，我們需要在容器啟動之前，在 .env 檔案中啟用這個功能，加入以下鍵值即可

SAIL_XDEBUG_MODE=develop,debug

加入後啟動容器

vendor/bin/sail up -d

由於通過 Laravel Sail 的開發環境，位於主機的 PhpStorm 並無法直接訪問到 PHP 直譯器，但是 PhpStorm 支援通過 Docker 配置它

按如圖所示操作新增位於 Docker 內的 PHP 直譯器，注意 PHP language level 一項也需要手動選擇為與 Docker 內一致的版本。

訪問瀏覽器的擴充套件商店搜尋 XDebug Helper 並安裝

如果使用 Edge 可以直接訪問 Xdebug helper - Microsoft Edge Addons

在 File >> Setting >> PHP >> Servers 按如圖配置

開啟 PhpStorm 的 XDebug 監聽

隨機修改 routes/web.php 中的程式碼，這裡使用

Route::get('/', function () {
    $a = 1;
    return view('welcome');
});

在 return 語句打上斷點

啟用 XDebug Helper 的 Debug 模式，並重新整理 localhost 頁面

此時 PhpStorm 可能彈出 Debug 連線的視窗，連線即可，便可以看到斷點的 Debug 資訊：

快取了路由又在 web.php 打斷點

使用了 sail php artisan route:cache 後，路由將直接由快取載入，將無法訪問到程式碼中的斷點。

PHPStorm 路徑對映配置錯誤

在配置 PhpStorm 的 Server 時，遠端的絕對路徑應該是 /var/www/html，這是專案在容器中的路徑，而非專案在子系統中的路徑。

PhpStorm 官方文件

Laravel Sail 官方文件

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

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