juliangut/phpdev Docker镜像文档

!Docker Pulls !Docker Stars !Build Status !Automated build

镜像概述和主要用途

基于Alpine Linux的PHP/PHP-FPM/Jenkins Docker镜像，专为开发和CI环境设计，追求最小镜像体积。适用于PHP应用的本地开发调试、CI/CD流程中的构建与测试，以及作为Jenkins CI流水线的slave节点。

核心功能和特性

• 基础配置：默认UTC时区
• 开发工具：
  • 预配置并启用最新Xdebug (3.x)，支持调试和代码覆盖率分析
  • 全局安装最新Composer (2.x)，便于依赖管理
  • 包含make构建工具，支持自动化构建流程
• PHP扩展：
  • 内置扩展：Multibyte String、cURL、Intl、OpenSSL、Zlib、BCMath、GD、OPcache
  • PECL扩展：APCu
• PHP-FPM增强：自动健康检查机制
• 多形态支持：提供CLI、PHP-FPM、Jenkins三种形态镜像

使用场景和适用范围

• CLI镜像：命令行脚本执行、Composer依赖管理、单元测试、代码静态分析等开发任务
• PHP-FPM镜像：Web应用开发环境，配合Nginx/Apache作为FastCGI后端
• Jenkins镜像：CI/CD流水线中的构建节点，支持PHP项目的自动化测试、代码质量检查和部署流程

可用标签

CLI

FPM

Jenkins

Jenkins镜像专为CI流水线中的Jenkins slave节点设计

环境变量

通用配置

STDOUT_LOG

• 类型：整数
• 默认值：0
• 描述：设置非零值将日志输出到stdout。默认PHP错误日志路径为/var/log/php/php.log。此设置不影响Xdebug会话日志，后者仍输出到/var/log/php/debug.log

Xdebug配置

XDEBUG_DISABLE

• 类型：整数
• 默认值：0
• 描述：设置非零值禁用Xdebug。不推荐，建议使用XDEBUG_MODE=off替代

XDEBUG_MODE

• 类型：字符串
• 默认值：develop,coverage,debug
• 描述：Xdebug运行模式。设置为off可禁用Xdebug。详见xdebug.mode文档

XDEBUG_CLIENT_HOST

• 类型：字符串
• 默认值：自动发现主机
• 描述：调试客户端主机地址。自动发现逻辑：优先使用host.docker.internal（若定义），否则自动检测远程主机IP

XDEBUG_CLIENT_PORT

• 类型：整数
• 默认值：9003
• 描述：调试客户端监听端口

XDEBUG_FILE_LINK_FORMAT

• 类型：字符串
• 默认值：未设置
• 描述：堆栈跟踪文件链接的协议格式，用于集成IDE。可使用预设值（如phpstorm、vscode、sublime）或自定义格式。自定义格式需注意转义特殊字符。详见xdebug.file_link_format文档

OPcache配置

OPCACHE_VALIDATE_TIMESTAMP

• 类型：整数
• 默认值：1
• 描述：设置为0禁用文件时间戳验证（生产环境推荐），1启用（开发环境默认）

OPCACHE_MEMORY_CONSUMPTION

• 类型：整数
• 默认值：128
• 描述：OPcache内存消耗限制（MB）

OPCACHE_MAX_ACCELERATED_FILES

• 类型：整数
• 默认值：1000
• 描述：最大缓存文件数量

环境变量更新说明

由于Xdebug 3升级，部分环境变量已变更或移除：

• XDEBUG_REMOTE_HOST 重命名为 XDEBUG_CLIENT_HOST
• XDEBUG_REMOTE_PORT 重命名为 XDEBUG_CLIENT_PORT
• 默认调试端口变更为 9003
• 移除 XDEBUG_REMOTE_AUTOSTART，改用动态启动方式（见调试章节）
• 移除 XDEBUG_IDE_KEY，如需使用需自定义Xdebug配置
• 移除 XDEBUG_PROFILER_ENABLE 和 XDEBUG_AUTO_TRACE，功能由 XDEBUG_MODE 控制

数据卷

/app

• 描述：默认工作目录。建议将项目根目录挂载到此卷，实现代码实时同步

/var/log/php

• 描述：PHP日志目录。包含PHP错误日志（php.log）、Xdebug调试日志（debug.log）和PHP-FPM日志

使用方法和配置说明

获取镜像

bash
# CLI镜像
docker pull juliangut/phpdev:latest

# FPM镜像
docker pull juliangut/phpdev:fpm-latest

# Jenkins镜像
docker pull juliangut/phpdev:jenkins-latest

运行容器

基础运行

bash
# 交互式运行CLI容器
docker run --rm -it -v `pwd`:/app juliangut/phpdev:latest

# 后台运行FPM容器
docker run -d -v `pwd`:/app juliangut/phpdev:fpm-latest

启动内置Web服务器

bash
docker run -d -p 8080:8080 -v `pwd`:/app juliangut/phpdev:latest php -S 0.0.0.0:8080 -t /app/public

Docker Compose示例：

yaml
version: "3"

services:
  app:
    image: juliangut/phpdev:latest
    ports:
      - 8080:8080
    volumes:
      - .:/app
    command: "php -S 0.0.0.0:8080 -t /app/public"

访问地址：http://localhost:8080

执行Composer命令

bash
# CLI镜像执行Composer
docker run --rm -v `pwd`:/app juliangut/phpdev:latest composer [命令]

# FPM镜像执行Composer
docker run --rm -v `pwd`:/app juliangut/phpdev:fpm-latest composer [命令]

Composer认证配置： 如需访问私有仓库，可挂载本地Composer认证文件：

bash
docker run --rm -v `pwd`:/app -v ~