Docker PHP镜像在macOS运行Linux容器时查找Windows路径启动失败

问题根因 #

你运行的Linux容器内加载了来自本地挂载目录的Windows版本PHP配置文件：
你本地./src目录下大概率存放了之前Windows环境下XAMPP生成的php.ini/.user.ini配置，容器启动时PHP会优先读取项目目录下的配置文件，调用了配置内写死的C:\xampp\php\ext\路径查找扩展，Linux环境下不存在该路径，直接触发启动致命错误，对应状态码254。

修复步骤 #

• 第一步：清理本地挂载目录的冗余配置
  检查./src目录下的php.ini、.user.ini等PHP配置文件，直接删除或重命名即可，容器默认会使用镜像自带的适配Linux环境的PHP配置，无需额外导入Windows环境的配置。
• 第二步（可选：如果需要自定义PHP配置）：
  1. 新建独立的配置目录（不要放在src业务代码目录下），比如./php-conf，在目录中新建自定义配置文件，所有路径要适配Linux规范
  2. 如果需要用到bz2扩展，先修改Dockerfile添加扩展安装逻辑：

  FROM php:8.0-apache
  RUN apt update && apt install -y libbz2-dev \
      && docker-php-ext-install mysqli bz2 \
      && docker-php-ext-enable mysqli bz2
  RUN apt-get update && apt-get upgrade -y
  

  3. 修改docker-compose.yml的php服务配置，挂载自定义配置目录：

  services:
    php-apache-environment:
      # 原有配置保留，新增下面的volumes项
      volumes:
        - ./src:/var/www/html/
        - ./php-conf:/usr/local/etc/php/conf.d/
  

• 第三步：重启容器生效
  执行以下命令重新构建启动服务：

  docker-compose down -v
  docker-compose up -d --build
  

验证方法 #

如果不确定是否为本地配置导致的问题，可以先临时注释掉docker-compose.yml中php服务挂载本地./src的配置行，直接启动官方镜像，若容器能正常运行即可100%确认是本地挂载目录的配置问题。

内容的提问来源于stack exchange，提问作者Dominik Gubrynowicz