PHP与Docker开发环境搭建使用Docker容器化PHP应用的完整指南-php教程-PHP中文网

docker是php开发者的“救星”因为它解决了环境不一致和依赖冲突问题，实现了开发、测试、生产环境的统一。1. 使用docker-compose.yml定义服务、网络和数据卷，实现多容器协同；2. 通过自定义dockerfile安装php扩展和工具，确保环境完整性；3. 利用volumes实现代码实时同步和数据持久化；4. 配置自定义网络使服务间通过服务名通信；5. 针对文件性能、xdebug调试、容器内命令执行和权限问题采取优化措施，如使用host.docker.internal、docker-compose exec命令和用户id匹配等方法，最终实现高效、可复现的php开发环境。

PHP与Docker开发环境搭建使用Docker容器化PHP应用的完整指南

在现代Web开发中，为PHP应用构建一个高效、稳定且可复现的开发环境，Docker无疑是我的首选工具。它能将所有服务——PHP运行时、Web服务器、数据库乃至缓存系统——打包进独立的容器，彻底告别“在我机器上能跑”的尴尬，让团队协作和部署变得异常顺畅。

搭建基于Docker的PHP开发环境，核心在于

docker-compose.yml

登录后复制

文件的编排。这就像是给你的应用画一张蓝图，告诉Docker需要哪些服务，它们之间如何协作。

首先，你需要一个项目目录。比如：

立即学习“PHP免费学习笔记（深入）”；

my-php-app/
├── src/ # 你的PHP代码
│   └── public/
│       └── index.php
├── docker-compose.yml
├── docker/
│   ├── nginx/
│   │   └── default.conf
│   └── php-fpm/
│       └── Dockerfile

登录后复制

然后是

docker-compose.yml

登录后复制

的编写。一个典型的配置会包含Nginx（作为Web服务器）、PHP-FPM（处理PHP代码）和MySQL（或PostgreSQL，作为数据库）。

version: '3.8'

services:
  nginx:
    image: nginx:stable-alpine
    ports:
      - "80:80"
    volumes:
      - ./src:/var/www/html # 将本地代码映射到容器
      - ./docker/nginx/default.conf:/etc/nginx/conf.d/default.conf # 映射Nginx配置
    depends_on:
      - php-fpm
    networks:
      - app-network

  php-fpm:
    build:
      context: ./docker/php-fpm # 构建自定义PHP镜像
      dockerfile: Dockerfile
    volumes:
      - ./src:/var/www/html
    networks:
      - app-network

  mysql:
    image: mysql:8.0
    environment:
      MYSQL_ROOT_PASSWORD: root_password
      MYSQL_DATABASE: my_database
      MYSQL_USER: my_user
      MYSQL_PASSWORD: my_password
    volumes:
      - db_data:/var/lib/mysql # 持久化数据库数据
    networks:
      - app-network

volumes:
  db_data: # 定义数据卷

networks:
  app-network: # 定义网络
    driver: bridge

登录后复制

接下来是自定义的

Dockerfile

登录后复制

（

docker/php-fpm/Dockerfile

登录后复制

），如果你需要安装特定的PHP扩展：

FROM php:8.2-fpm-alpine

# 安装常用扩展
RUN apk add --no-cache \
    autoconf \
    build-base \
    libzip-dev \
    libpng-dev \
    jpeg-dev \
    freetype-dev \
    imagemagick-dev \
    onig-dev \
    libxml2-dev \
    icu-dev \
    pcre-dev \
    sqlite-dev \
    zlib-dev \
    gmp-dev \
    openssl-dev \
    libpq \
    libmcrypt-dev \
    git \
    zip \
    unzip \
    curl \
    vim \
    && docker-php-ext-install -j$(nproc) pdo_mysql gd opcache pcntl intl soap zip exif bcmath gmp \
    && docker-php-ext-configure gd --with-freetype --with-jpeg \
    && docker-php-ext-enable opcache \
    && docker-php-source delete

# 安装Composer
COPY --from=composer:latest /usr/bin/composer /usr/bin/composer

WORKDIR /var/www/html

登录后复制

Nginx的

default.conf

登录后复制

(

docker/nginx/default.conf

登录后复制

)：

server {
    listen 80;
    index index.php index.html;
    error_log /var/log/nginx/error.log;
    access_log /var/log/nginx/access.log;
    root /var/www/html/public; # 你的应用入口目录

    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }

    location ~ \.php$ {
        try_files $uri =404;
        fastcgi_split_path_info ^(.+\.php)(/.+)$;
        fastcgi_pass php-fpm:9000; # php-fpm服务名和端口
        fastcgi_index index.php;
        include fastcgi_params;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        fastcgi_param PATH_INFO $fastcgi_path_info;
    }
}

登录后复制

最后，在项目根目录运行

docker-compose up -d

登录后复制

，你的PHP应用环境就启动了。访问

http://localhost

登录后复制

就能看到你的应用了。

为什么说Docker是PHP开发者的“救星”？

回想我刚开始接触PHP开发那会儿，WAMP、MAMP、XAMPP这些集成环境是主流。它们固然方便，但随着项目增多，PHP版本、扩展库、甚至Apache模块之间的冲突简直是家常便饭。一个项目需要PHP 7.4，另一个又必须用PHP 8.1，来回切换简直是噩梦，更别提那些“在我机器上能跑，你那儿就不行”的经典场景。这不仅拖慢了开发进度，也让团队协作变得异常困难。

Docker的出现，彻底改变了这一切。它提供了一种轻量级、可移植的容器化技术，让每个服务（PHP-FPM、Nginx、MySQL等）都运行在独立的、隔离的环境中。这意味着，你可以为每个项目定制一套完全独立的开发环境，互不干扰。新同事入职？一份

docker-compose.yml

登录后复制

文件，几分钟就能跑起来项目，省去了漫长的环境配置时间。开发环境与生产环境的高度一致性，也大大减少了部署时的意外。对我而言，这不仅是工具的升级，更是开发心智模式的转变，从“配置环境”变成了“定义环境”。

AppMall应用商店

AI应用商店，提供即时交付、按需付费的人工智能应用服务

查看详情

docker-compose.yml

登录后复制

：如何构建你的PHP应用生态？

刚才我们看到了一个基础的

docker-compose.yml

登录后复制

示例，但它远不止如此。这个文件是定义多容器应用的关键，它描述了服务（service）、网络（network）和数据卷（volume）。

services
登录后复制
：这是你应用的核心组件。
- nginx
  登录后复制
  : 作为反向代理和静态文件服务。
```
image
```
  登录后复制
  指定了基础镜像，
```
ports
```
  登录后复制
  将容器的80端口映射到宿主机的80端口，这样你就能通过浏览器访问。
```
volumes
```
  登录后复制
  是其精髓，它把本地的PHP代码和Nginx配置文件映射到容器内部，实现代码的实时同步和配置的灵活修改。
- php-fpm
  登录后复制
  : 专门处理PHP脚本的进程管理器。我们通常不会直接使用官方的
```
php-fpm
```
  登录后复制
  镜像，而是通过
```
build
```
  登录后复制
  指令指向一个自定义的
```
Dockerfile
```
  登录后复制
  。这个
```
Dockerfile
```
  登录后复制
  允许你安装项目所需的各种PHP扩展（比如
```
gd
```
  登录后复制
  处理图片、
```
intl
```
  登录后复制
  处理国际化、
```
xdebug
```
  登录后复制
  用于调试等），以及Composer等工具。这保证了PHP环境的定制化和完整性。
- mysql
  登录后复制
  : 你的数据库服务。
```
environment
```
  登录后复制
  变量用于设置数据库的root密码、数据库名、用户名和密码，这些都是容器启动时自动配置的。
```
volumes
```
  登录后复制
  中的
```
db_data
```
  登录后复制
  是一个命名数据卷，它的作用是持久化数据库数据，即使容器被删除，数据也不会丢失，下次启动时数据依然存在。
volumes
登录后复制
: 用于数据持久化。除了上面提到的
```
db_data
```
登录后复制
，你也可以为其他服务定义数据卷，确保重要数据不会随容器的生命周期而消失。
networks
登录后复制
: 定义服务之间的通信方式。
```
app-network
```
登录后复制
是一个自定义的桥接网络，所有连接到这个网络的容器都可以通过服务名互相访问（比如Nginx通过
```
php-fpm:9000
```
登录后复制
连接到PHP-FPM）。这种内部网络隔离了应用服务与外部，增强了安全性。

理解这些组件如何协同工作，你就掌握了Docker构建PHP应用生态的精髓。你可以根据项目需求，轻松地加入Redis、RabbitMQ等更多服务，共同构建一个完整的开发和运行环境。

避坑指南：Docker化PHP开发中常见的挑战与应对

尽管Docker带来了诸多便利，但在实际使用中，也难免遇到一些“坑”，尤其是在PHP开发场景下。

一个比较常见的挑战是文件共享性能问题。在macOS和Windows上，Docker Desktop通过虚拟机来运行Linux容器，宿主机与容器之间的文件卷映射（

volumes

登录后复制

）在某些情况下可能会导致IO性能下降，尤其当项目文件数量庞大时。为了解决这个问题，可以尝试以下方法：

macOS/Windows用户： 升级Docker Desktop到最新版本，它通常会引入如VirtioFS等更高效的文件共享技术。对于某些极端情况，考虑使用Mutagen等第三方工具来同步文件，这能显著提升性能。
Linux用户： 原生支持，性能通常不是问题。

再来是Xdebug调试配置。在Docker容器中调试PHP代码，需要确保Xdebug正确配置，并且你的IDE（如PhpStorm、VS Code）能够连接到容器内的Xdebug服务。关键在于

xdebug.client_host

登录后复制

和

xdebug.client_port

登录后复制

这两个配置项。

```
xdebug.client_host
```
登录后复制
通常需要设置为宿主机的IP地址，让Xdebug知道往哪里发送调试信息。在
```
docker-compose.yml
```
登录后复制
中，PHP-FPM服务下可以添加
```
extra_hosts: - "host.docker.internal:host-gateway"
```
登录后复制
，然后将
```
xdebug.client_host
```
登录后复制
设为
```
host.docker.internal
```
登录后复制
，这在Docker Desktop上非常方便。
确保容器的9003端口（Xdebug默认端口）对宿主机是开放的，或者你的IDE监听的是Xdebug配置的端口。

容器内执行Composer或Artisan命令也是日常操作。你不能直接在宿主机执行

composer install

登录后复制

，因为那会使用宿主机的PHP环境。正确的做法是通过

docker-compose exec

登录后复制

命令进入到PHP-FPM容器内执行：

docker-compose exec php-fpm composer install
docker-compose exec php-fpm php artisan migrate

登录后复制

这保证了所有依赖和操作都在容器的隔离环境中进行。

最后是权限问题。有时你会发现容器内的Nginx或PHP-FPM无法写入某些目录（如日志目录、缓存目录），这通常是文件权限不匹配导致的。容器内的进程默认以

www-data

登录后复制

或其他用户运行，而宿主机上你的用户ID可能不同。一种解决方案是在

Dockerfile

登录后复制

中创建与宿主机用户ID匹配的用户，或者在

docker-compose.yml

登录后复制

的

php-fpm

登录后复制

服务下添加

user: "1000:1000"

登录后复制

（假设你的宿主机用户ID和组ID都是1000）。另外，确保你的本地项目目录对容器有写入权限。

这些小细节，虽然初次遇到可能会让你挠头，但一旦掌握了它们，Docker化PHP开发就会变得异常顺手和高效。

以上就是PHP与Docker开发环境搭建使用Docker容器化PHP应用的完整指南的详细内容，更多请关注php中文网其它相关文章！

大家都在看：

PHP 使用 FPDI 合并 PDF 文件并智能适应页面方向 PHP运行时获取最大内存限制（字节）及内存使用监控使用PHP恢复SQL文件：常见问题与解决方案 PHP接口怎么加密_PHP接口加密方法及数据传输安全。 php指针怎么用_PHP指针概念与引用操作方法教程

PHP与Docker开发环境搭建 使用Docker容器化PHP应用的完整指南

为什么说Docker是PHP开发者的“救星”？

docker-compose.yml登录后复制：如何构建你的PHP应用生态？

避坑指南：Docker化PHP开发中常见的挑战与应对

大家都在看：

PHP与Docker开发环境搭建使用Docker容器化PHP应用的完整指南

docker-compose.yml
登录后复制
：如何构建你的PHP应用生态？