避坑!用 Docker 搞定 PHP 开发环境搭建(Mac、Docker、Nginx、PHP-FPM、XDebug、PHPStorm、VSCode)

文章版本: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的便利,我会不定期的更新这篇文章,这也是我在文章开头设置了一个版本号的原因,希望对大家有所帮助。

本作品采用《CC 协议》,转载必须注明作者和本文链接
本帖由系统于 4年前 自动加精
讨论数量: 28
  • 老哥,你没有遇到过用docker开发访问一个接口需要6~7秒吗?我查了原因是因为mac的文件格式和Linux不同,每次访问laravel框架加载文件都要作大量的格式转换.以前也想用docker开发,后来因为这个原因放弃了.
  • docker for mac volume slow
4年前 评论

Mark 一下,改天试试

4年前 评论

很棒,而且说明好详细,感谢 :grin:

4年前 评论

windwos的docker我还没爬出来,难受 :joy:

4年前 评论

E: Release file for http://mirrors.aliyun.com/debian-security/... is not valid yet (invalid for another 1d 14h 50min 7s). Updates for this repository will not be applied.
E: Release file for http://mirrors.aliyun.com/debian/dists/bus... is not valid yet (invalid for another 1d 17h 10min 48s). Updates for this repository will not be applied.
E: Release file for http://mirrors.aliyun.com/debian/dists/bus... is not valid yet (invalid for another 1d 17h 10min 48s). Updates for this repository will not be applied.

好像是镜像源里还是有问题?楼主有遇到这个问题吗?

4年前 评论

笔记本性能不够,内存小完全不够装虚拟机的,用上了docker,但是感觉docker里面安装php拓展实在是太耗时间了,于是本机装了php,虚拟机里面的nginx调用本机的php-fpm,很是开心

4年前 评论
Bin 4年前

使用FROM php:7.3.8-fpm Dockerfile在build时报错,mac环境
error: 'redis' does not exist

usage: /usr/local/bin/docker-php-ext-enable [options] module-name [module-name ...]
ie: /usr/local/bin/docker-php-ext-enable gd mysqli
/usr/local/bin/docker-php-ext-enable pdo pdo_mysql
/usr/local/bin/docker-php-ext-enable --ini-name 0-apc.ini apcu apc

Possible values for module-name:
bcmath.so calendar.so dba.so exif.so gd.so gettext.so iconv.so imagick.so mcrypt.so memcached.so mysqli.so opcache.so pcntl.so pdo_mysql.so shmop.so sockets.so sodium.so sysvmsg.so sysvsem.so sysvshm.so

Some of the above modules are already compiled into PHP; please check
the output of "php -i" to see which modules are already loaded.
The command '/bin/sh -c 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' returned a non-zero code: 1

4年前 评论

@declandragon windows 下使用docker很多问题,各种文件访问权限问题,打开网页还很卡,还是linux下使用比较顺溜。

4年前 评论

@tsin 是的额,好多问题~爬不出来了 :joy:

4年前 评论
Bin 4年前

怎么不装 mysql 这一部分使用 Docker Compose 来编排

4年前 评论

mark下,挺详细的,有时间试试

4年前 评论

error: 'imagick' does not exist 7.38总会报这个错。

4年前 评论

4G mac air 看着飕飕发抖

4年前 评论

明显搞成docker-compose文件要好点吧

4年前 评论

@jiacongcong 我的是网络问题,我重试几次换了网络之后成功了

4年前 评论

VScode定位不到第三方扩展有没有什么好办法, 比如Seaslog、redis

4年前 评论

#基于版本 hub.docker.com/_/php?tab=tags FROM php:7.3.23-fpm

#github.com/mlocati/docker-php-exte... ADD install-php-extensions /usr/local/bin/

#apt-get替换阿里源 RUN sed -i s@/deb.debian.org/@/mirrors.aliyun.com/@g /etc/apt/sources.list
&& apt-get clean
&& apt-get update

#用pecl安装插件 RUN pecl install redis-5.3.2
&& docker-php-ext-enable redis

RUN pecl install swoole-4.5.5
&& docker-php-ext-enable swoole

#用install-php-extensions 安装插件 RUN chmod uga+x /usr/local/bin/install-php-extensions && sync
&& install-php-extensions gd mcrypt memcached opcache imagick

#添加标签 LABEL Author="BBX" LABEL Version="2020.10.23" LABEL Description="PHP 7.3.23 开发和生产环境镜像"

3年前 评论
sunny123456 2年前

Mark 一下,改天试试

3年前 评论

docker消耗太多系统资源了,还是用开发环境工具比较方便。 我推荐servbay,安装好就可以用了,而且又不会占用很多资源,比MAMP方便。

4个月前 评论

讨论应以学习和精进为目的。请勿发布不友善或者负能量的内容,与人为善,比聪明更重要!