避坑！用 Docker 搞定 PHP 開發環境搭建（Mac、Docker、Nginx、PHP-FPM、XDebug、PHPStorm、VSCode）

climberone發表於2019-07-18
DockerPHP開發環境MacNginxORMVSCode

文章版本：2019.8

本次更新主要是對環境版本進行了更新，例如php 7.3.7升級到了7.3.8，另外之前的版本有同學踩了坑，主要是官方docker映象php:7.3.7-fpm和php:7.3.8-fpm使用了不同版本的debian，後面會提到，請各位同學留意。

因為最近換電腦的緣故需要重新部署一下本地的開發環境，之前採用的虛擬機器方案，佔用磁碟空間實在是太大，心疼SSD那麼點地方，所以這次採用了Docker的方案來部署。
關於這次部署的原則，我的想法是儘量使用官方的映象來實現，儘量不改動或少改動映象。因為是本地的開發環境，所以想多嚐嚐鮮，儘量使用高版本的軟體來實現。
從結果上來說，希望能給同樣有需要搭建環境的同學起到一些幫助，少踩一些坑，如果能按照這篇文章的步驟一次搞定那是最好了。

先來說一下環境：

  • Docker 19.03.1
  • Nginx 1.17.2
  • PHP 7.3.8
  • XDebug 2.7.2
  • PhpStorm 2019.2
  • VSCode 1.36.1

用到的PHP擴充套件版本

  • i magick-3.4.4
  • mcrypt-1.0.2
  • memcached-3.1.3
  • redis-5.0.2
  • xdebug-2.7.2
  • swoole-4.4.3

1、Docker的安裝

這裡大家直接在Docker官網下載Docker for Mac就好了，直接按照提示操作即可，此處就不贅述了。

2、安裝Nginx

地址：https://hub.docker.com/_/nginx
直接執行 docker pull nginx 拉取最新的映象，目前是1.17.2；
根據上面的地址我們可以看到官方提供的一些文件，我們按照操作即可，我個人採用的方案是先將nginx的整個配置目錄copy到本地一份，然後在執行的時候將目錄繫結到nginx容器的配置目錄，這樣修改配置更加方便一些。

將nginx配置目錄copy到本地：

$ docker run --name tmp-nginx -d nginx
$ docker cp tmp-nginx:/etc/nginx /Users/yourname/Workspace/etc/nginx
$ docker rm -f tmp-nginx

說明：/Users/yourname/Workspace/etc，這個是我個人的工作目錄，到時候根據情況換成自己的就行；命令的作用就是啟一個後臺執行的nginx容器，將配置目錄copy出來之後終止執行並刪除容器。

可以先執行一下看看效果：

$ docker run --name run-nginx -d -p 80:80 -v /Users/yourname/Workspace/www:/usr/share/nginx/html:ro nginx

說明：-v引數繫結本地的一個目錄到nginx容器中的web目錄，這裡面沒有繫結配置目錄，大家可以在web目錄下建立一個hello.html，通過瀏覽器訪問http://localhost/hello.html看看效果，這之後可以大家可以先刪除容器，後面我們改完配置再來啟動它。
刪除方法：

$ docker rm -f run-nginx

3、安裝php-fpm

地址：https://hub.docker.com/_/php
因為這裡我們需要安裝一些開發時用到的PHP擴充套件，所以最好的辦法是根據Dockerfile生成我們自己的映象，如下是我的Dockerfile，大家可以參考，可以根據情況刪減不需要的擴充套件，否則生成的映象會比較大。

Dockerfile內容如下：

# 從官方基礎版本構建
FROM php:7.3.7-fpm
# 官方版本預設安裝擴充套件: 
# Core, ctype, curl
# date, dom
# fileinfo, filter, ftp
# hash
# iconv
# json
# libxml
# mbstring, mysqlnd
# openssl
# pcre, PDO, pdo_sqlite, Phar, posix
# readline, Reflection, session, SimpleXML, sodium, SPL, sqlite3, standard
# tokenizer
# xml, xmlreader, xmlwriter
# zlib

# 更新為國內映象
RUN mv /etc/apt/sources.list /etc/apt/sources.list.bak \
    && echo 'deb http://mirrors.163.com/debian/ stretch main non-free contrib' > /etc/apt/sources.list \
    && echo 'deb http://mirrors.163.com/debian/ stretch-updates main non-free contrib' >> /etc/apt/sources.list \
    && echo 'deb http://mirrors.163.com/debian-security/ stretch/updates main non-free contrib' >> /etc/apt/sources.list \
    && apt-get update

# bcmath, calendar, exif, gettext, sockets, dba, 
# mysqli, pcntl, pdo_mysql, shmop, sysvmsg, sysvsem, sysvshm 擴充套件
RUN docker-php-ext-install -j$(nproc) bcmath calendar exif gettext sockets dba mysqli pcntl pdo_mysql shmop sysvmsg sysvsem sysvshm iconv

# GD 擴充套件
RUN apt-get install -y --no-install-recommends libfreetype6-dev libjpeg62-turbo-dev libpng-dev \
    && rm -r /var/lib/apt/lists/* \
    && docker-php-ext-configure gd --with-freetype-dir=/usr/include/ --with-jpeg-dir=/usr/include/ \
    && docker-php-ext-install -j$(nproc) gd

# imagick 擴充套件
RUN export CFLAGS="$PHP_CFLAGS" CPPFLAGS="$PHP_CPPFLAGS" LDFLAGS="$PHP_LDFLAGS" \
    && apt-get install -y --no-install-recommends libmagickwand-dev \
    && rm -r /var/lib/apt/lists/* \
    && pecl install imagick-3.4.4 \
    && docker-php-ext-enable imagick

# mcrypt 擴充套件 
RUN apt-get install -y --no-install-recommends libmcrypt-dev \
    && rm -r /var/lib/apt/lists/* \
    && pecl install mcrypt-1.0.2 \
    && docker-php-ext-enable mcrypt

# Memcached 擴充套件 
RUN apt-get install -y --no-install-recommends libmemcached-dev zlib1g-dev \
    && rm -r /var/lib/apt/lists/* \
    && pecl install memcached-3.1.3 \
    && docker-php-ext-enable memcached

# redis 擴充套件
RUN pecl install redis-5.0.0 && docker-php-ext-enable redis

# opcache 擴充套件 
RUN docker-php-ext-configure opcache --enable-opcache && docker-php-ext-install opcache

# xdebug 擴充套件
RUN pecl install xdebug-2.7.2 && docker-php-ext-enable xdebug

# swoole 擴充套件
RUN pecl install swoole-4.4.0 && docker-php-ext-enable swoole

# 映象資訊
LABEL Author="Stone"
LABEL Version="2019.7"
LABEL Description="PHP 7.3.7 開發環境映象.

說明：這個Dockerfile我參考了https://www.jianshu.com/p/20fcca06e27e作者的內容，並做了一些調整，大家可以根據自己情況增減，因為是開發環境所以最好把xdebug留著，我們們後面也會用到；

下面是將RUN串聯起來的Dockerfile，這樣生成的映象能小一些，但是依然有636M，官方的php:7.3.7-fpm的映象是371M，如果想優化也可以從官方提供的Alpine映象生成，我們們這裡就先簡單粗暴了。

上面的內容沒有更新，依然是上個文章版本的內容，為的是有個對比，請使用以下最新的Dockerfile。

FROM php:7.3.8-fpm

RUN mv /etc/apt/sources.list /etc/apt/sources.list.bak \
    && echo 'deb http://mirrors.aliyun.com/debian/ buster main non-free contrib' > /etc/apt/sources.list \
    && echo 'deb http://mirrors.aliyun.com/debian-security buster/updates main' >> /etc/apt/sources.list \
    && echo 'deb http://mirrors.aliyun.com/debian/ buster-updates main non-free contrib' >> /etc/apt/sources.list \
    && echo 'deb http://mirrors.aliyun.com/debian/ buster-backports main non-free contrib' >> /etc/apt/sources.list \
    && apt-get update \
    && export CFLAGS="$PHP_CFLAGS" CPPFLAGS="$PHP_CPPFLAGS" LDFLAGS="$PHP_LDFLAGS" \
    && apt-get install -y --no-install-recommends libfreetype6-dev libjpeg62-turbo-dev libpng-dev libmagickwand-dev libmcrypt-dev libmemcached-dev zlib1g-dev \
    && rm -rf /var/lib/apt/lists/* \
    && docker-php-ext-configure gd --with-freetype-dir=/usr/include/ --with-jpeg-dir=/usr/include/ \
    && docker-php-ext-install -j$(nproc) bcmath calendar exif gettext sockets dba mysqli pcntl pdo_mysql shmop sysvmsg sysvsem sysvshm iconv gd \
    && pecl install imagick-3.4.4 mcrypt-1.0.2 memcached-3.1.3 redis-5.0.2 xdebug-2.7.2 swoole-4.4.3\
    && docker-php-ext-enable imagick mcrypt memcached redis xdebug swoole \
    && docker-php-ext-configure opcache --enable-opcache && docker-php-ext-install opcache

LABEL Author="Stone"
LABEL Version="2019.8"
LABEL Description="PHP 7.3.8 開發環境映象. "

說一下踩的坑：apt-get的源最好換成國內的源，否則可能會在構建映象的時候卡死；因為預設情況下官方容器是基於Debian的，查詢源的時候很多都是過時的，如當前的Debian代號是stretch，卻使用了jessie的包那肯定是會報錯的，“E: Unable to correct problems, you have held broken packages.”；大家直接按照我上面的Dockerfile生成映象即可，測試通過。
另外需要注意預設的php:7.3.7-fpm是基於Debian 9構建的，代號是stretch；而php:7.3.8-fpm是基於Debian 10，代號是buster。使用不同版本的Debian可以用tag末尾為-stretch或者-buster進行選擇。

在Dockerfile所在目錄下執行：

docker build -t my-php-fpm:2019.8 .

-t引數設定映象名稱和標籤，請根據自己情況命名，映象建立完成之後，可以像上面我們copy出nginx配置一樣，將php的相關配置也copy到本地。

$ docker run --name tmp-my-php-fpm -d my-php-fpm:2019.7
$ docker cp tmp-my-php-fpm:/usr/local/etc /Users/yourname/Workspace/etc/php
$ docker rm -f tmp-my-php-fpm

4、修改nginx、php-fpm、xdebug的配置檔案

修改nginx配置檔案，開啟/Users/yourname/Workspace/etc/nginx/default.conf，加入下面的內容：

 location ~ \.php$ {
        fastcgi_pass   php-fpm-container:9000;
        fastcgi_index  index.php;
        fastcgi_param  SCRIPT_FILENAME  /var/www/html$fastcgi_script_name;
        fastcgi_param  SCRIPT_NAME      $fastcgi_script_name;
        include        fastcgi_params;
    }

增加的內容裡面有一處需要說明，“php-fpm-container”這個是我們們自己建立的php-fpm容器的別名，具體是在執行時候指定的，之後我們們會提到。

修改php相關配置檔案，進入/Users/yourname/Workspace/etc/php下，將php.ini-development複製改名為php.ini，配置內容根據自己情況修改即可。
修改xdebug的配置檔案，/Users/yourname/Workspace/etc/php/conf.d/docker-php-ext-xdebug.ini，加入如下內容

xdebug.remote_enable = On
xdebug.remote_handler = dbgp
xdebug.remote_host = host.docker.internal 
xdebug.remote_port = 9001
xdebug.remote_log = /var/log/php/xdebug.log
xdebug.idekey = PHPSTOR

以上設定主要是開啟xdebug的遠端除錯模式，因為php-fpm使用了9000埠，所以這裡我們把xdebug的埠改為了9001；“host.docker.internal”是docker 18.03新加入的，可以解析獲得宿主機的ip地址，這樣就不用寫死ip地址了。

5、啟動php-fpm、nginx容器

$ docker run --name run-my-php-fpm \
-v /Users/yourname/Workspace/www:/var/www/html \
-v /Users/yourname/Workspace/etc/php:/usr/local/etc \
-v /Users/yourname/Workspace/log/php:/var/log/php \
-d my-php-fpm:2019.8
$ docker run --name run-nginx \
-p 80:80 \
--link run-my-php-fpm:php-fpm-container \
-v /Users/yourname/Workspace/www:/usr/share/nginx/html \
-v /Users/yourname/Workspace/etc/nginx:/etc/nginx \
-v /Users/yourname/Workspace/log/nginx:/var/log/nginx \
-d nginx

說明：我將配置目錄、日誌目錄和web目錄都分別進行了繫結，方便在本地環境中修改。還記得上面提到的nginx中有個配置填寫的“php-fpm-container”嗎？實際上就是在這裡指定的，連線兩個容器，並給php-fpm容器起了個別名，配置中通過別名訪問。

在/Users/yourname/Workspace/www中建立一個phpinfo.php檔案，輸出php資訊，通過http://localhost/phpinfo.php訪問來檢視。

6、安裝Chrome瀏覽器外掛xdebug helper

可能會被牆，請自行解決。

7、PhpStorm除錯環境配置

建立/Users/yourname/Workspace/www/xdebug/demo.php，php檔案裡面隨便寫點php程式碼，也可以通過PhpStorm新建立一個空專案，但是位置要在我們和php-fpm容器繫結的目錄。

選單：PhpStorm->Preferences… 進入偏好設定，按照下圖進行設定。

根據上圖提示進入CLI Interpreter設定視窗，點“+”新增配置。


繼續配置Debug相關設定，如下圖：

進入主介面，選擇右上的“Add Configuration...”

進入debug配置視窗後選擇“+”，選擇“PHP Web Page“，設定名稱後進入Servers設定，同時設定Start URL：“/xdebug/demo.php”


進入主視窗，在程式中打幾個斷點，然後點選那個綠色的甲蟲就可以了。

8、VSCode除錯環境配置

首先安裝PHP Debug外掛，然後開啟上面建立的xdebug目錄。如下圖所示，進入除錯皮膚，點齒輪選擇PHP，然後會建立一個launch.json檔案，修改這個檔案加入pathMappings配置，這個配置引數用於設定伺服器路徑與本地路徑的對應關係，低版本使用的是localSourceRoot和serverSourceRoot，目前已經被廢除。另外記得將埠改為9001。

進入demo.php，隨意設定兩個斷點，然後點左側的執行按鈕，進入除錯模式，接下來重新整理http://localhost/xdebug/demo.php會返回到VSCode的除錯視窗，左側已經列出除錯資訊，可選擇單步執行跟蹤程式的執行。

結尾：實際上這次部署環境踩了不少坑，主要原因是網上的資料都比較陳舊，很多文章也沒有後續的更新，或者方向和我不太一致，例如hub中直接就有xdebug的映象，但是我還是想盡量用官方提供的映象自己建立，為了避免踩坑，大家最好還是多多參考官方文件，一般都寫的比較清楚了。得益於docker的便利，我會不定期的更新這篇文章，這也是我在文章開頭設定了一個版本號的原因，希望對大家有所幫助。

相關文章