使用 PhpStorm 来开发和 Debug Laravel Sail 项目

如果遇到问题，可以私信问我，将在能力范围内尽量解答。

Laravel Sail 安装

Laravel Sail 是为 Laravel 提供的基于 Docker 的开发环境，可同时搭建包含 PHP、MySQL、Redis，XDebug 在内的开发环境，优势：

• 降低开发环境的搭建难度
• 将对主机已有环境的影响降至最低
• 统一团队开发环境

在 WSL 内使用指令：

curl -s https://laravel.build/<项目名称> | bash

执行后，将在当前目录下建立一个 <项目名称> 的文件夹，并在里面构建一个 Laravel Sail 项目。

成功创建 Laravel 项目后，我们通过 cd 指令进入项目目录

cd <项目名称>

Dockerfile 修改

安装 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://laravel.com/docs/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 

PhpStorm 打开项目

File >> Open 在子系统的目录中选择我们的项目

打开项目后，可以直接在 Terminal 中运行需要在子系统中运行的指令，从而摆脱来回切换 PhpStorm 和 Windows Terminal 的麻烦。

将项目目录及内其内的文件权限修改为 777，方便使用 PhpStorm 进行编辑。

sudo chmod 777 ./ -R 

这样之后就可以关闭独立的 WSL 窗口了，直接在 PhpStorm 的 Terminal 窗口启动即可。

.env 修改

为了能够使用 Xdebug ，我们需要在容器启动之前，在 .env 文件中启用这个功能，加入以下键值即可

SAIL_XDEBUG_MODE=develop,debug

加入后启动容器

vendor/bin/sail up -d

PhpStorm 配置 PHP 解释器

由于通过 Laravel Sail 的开发环境，位于主机的 PhpStorm 并无法直接访问到 PHP 解释器，但是 PhpStorm 支持通过 Docker 配置它

按如图所示操作添加位于 Docker 内的 PHP 解释器，注意 PHP language level 一项也需要手动选择为与 Docker 内一致的版本。

浏览器 XDebug Helper 扩展

访问浏览器的扩展商店搜索 XDebug Helper 并安装

如果使用 Edge 可以直接访问 Xdebug helper - Microsoft Edge Addons

PhpStorm 配置 Servers

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

Enjoy it~

打开 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