Docker环境下Laravel开发环境搭建指南

Docker环境下Laravel开发环境搭建指南

docs Source repo for Docker's Documentation 项目地址: https://gitcode.com/gh_mirrors/docs3/docs

前言

在现代Web开发中，Docker已经成为构建标准化开发环境的重要工具。本文将详细介绍如何使用Docker为Laravel项目搭建一个完整的开发环境，该环境不仅包含PHP-FPM、Nginx和PostgreSQL等基础服务，还特别针对开发需求集成了Xdebug等调试工具。

环境架构设计

核心组件

1. PHP-FPM服务：基于生产环境镜像扩展，添加了开发所需功能
2. Nginx服务：作为Web服务器处理HTTP请求
3. PostgreSQL数据库：可根据需要替换为MySQL或MariaDB
4. Workspace容器（可选）：用于执行Artisan命令、前端构建等开发任务

目录结构解析

my-laravel-app/
├── app/                # Laravel应用核心代码
├── docker/             # Docker相关配置
│   ├── common/         # 通用配置
│   ├── development/    # 开发环境专用配置
│   └── production/     # 生产环境配置
├── compose.dev.yaml    # 开发环境Compose文件
└── compose.prod.yaml   # 生产环境Compose文件

这种结构将Docker配置与Laravel项目代码分离，便于管理和维护。

详细配置指南

PHP-FPM开发镜像构建

开发环境下的PHP-FPM镜像基于生产镜像扩展，主要添加了以下功能：

1. Xdebug配置：支持断点调试和性能分析
2. 用户权限调整：解决容器内外文件权限问题
3. 开发工具集成：便于本地开发和调试

FROM production AS development

# Xdebug配置参数
ARG XDEBUG_ENABLED=true
ARG XDEBUG_MODE=develop,coverage,debug,profile
ARG XDEBUG_HOST=host.docker.internal

USER root

# 安装并配置Xdebug
RUN if [ "${XDEBUG_ENABLED}" = "true" ]; then \
    pecl install xdebug && \
    docker-php-ext-enable xdebug && \
    # 详细配置省略...
fi

# 用户权限处理
ARG UID=1000
ARG GID=1000
RUN groupadd -g ${GID} www && \
    useradd -m -u ${UID} -g www -s /bin/bash www

# 设置工作目录和入口脚本
WORKDIR /var/www
COPY ./docker/development/php-fpm/entrypoint.sh /usr/local/bin/
RUN chmod +x /usr/local/bin/entrypoint.sh

USER www
ENTRYPOINT ["/usr/local/bin/entrypoint.sh"]
CMD ["php-fpm"]

Workspace容器配置

Workspace容器为开发提供了便利的CLI环境，包含：

1. PHP CLI工具链
2. Node.js环境（通过NVM管理）
3. Composer依赖管理
4. 数据库客户端工具

FROM php:8.4-cli

# 安装系统依赖和PHP扩展
RUN apt-get update && apt-get install -y --no-install-recommends \
    curl unzip libpq-dev libzip-dev && \
    docker-php-ext-install pdo_pgsql zip && \
    pecl install xdebug && docker-php-ext-enable xdebug

# 配置开发用户
ARG UID=1000
ARG GID=1000
RUN groupadd -g ${GID} www && \
    useradd -m -u ${UID} -g www -s /bin/bash www

# 安装Node.js环境
USER www
RUN curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.0/install.sh | bash && \
    # Node安装命令省略...

WORKDIR /var/www
CMD ["bash"]

Docker Compose开发配置

compose.dev.yaml文件定义了完整的开发环境服务：

services:
  web:
    image: nginx:latest
    volumes:
      - ./:/var/www
      - ./docker/development/nginx/nginx.conf:/etc/nginx/nginx.conf:ro
    ports:
      - "80:80"
    networks:
      - laravel-development

  php-fpm:
    build:
      context: .
      dockerfile: ./docker/common/php-fpm/Dockerfile
      target: development
      args:
        UID: ${UID:-1000}
        GID: ${GID:-1000}
    volumes:
      - ./:/var/www
    networks:
      - laravel-development

  # 其他服务配置省略...

开发环境启动与使用

启动命令

docker compose -f compose.dev.yaml up --build -d

此命令将：

1. 构建所有自定义镜像
2. 创建并启动所有定义的服务
3. 在后台运行容器

常见开发任务

1. 执行Artisan命令：

   docker compose exec workspace php artisan list
   

2. 前端资源构建：

   docker compose exec workspace npm run dev
   

3. 数据库迁移：

   docker compose exec workspace php artisan migrate
   

开发环境优化建议

1. 文件同步性能：对于大型项目，考虑使用cached或delegated卷挂载选项提高性能
2. Xdebug配置：根据IDE调整XDEBUG_IDE_KEY和XDEBUG_HOST参数
3. 多阶段构建：利用Docker的多阶段构建减少最终镜像大小
4. 本地缓存：配置Composer和NPM使用容器内的缓存目录加速安装

生产环境对比

开发环境与生产环境的主要差异：

| 特性 | 开发环境 | 生产环境 | |------|---------|---------| | Xdebug | 启用 | 禁用 | | 错误显示 | 开启 | 关闭 | | 优化配置 | 未启用 | 启用OPcache等 | | 镜像层 | 更多开发工具 | 最小化 |

总结

通过Docker搭建Laravel开发环境可以带来以下优势：

1. 环境一致性：团队所有成员使用相同的开发环境
2. 隔离性：不污染主机系统，避免依赖冲突
3. 快速切换：轻松在不同PHP版本或数据库之间切换
4. 接近生产：开发环境基于生产镜像构建，减少部署时的差异

这种基于Docker的开发环境配置既保持了与生产环境的高度一致，又提供了开发所需的灵活性和便利性，是现代化Laravel项目开发的理想选择。

docs Source repo for Docker's Documentation 项目地址: https://gitcode.com/gh_mirrors/docs3/docs