PHP源码Docker运行异常排查指南

本文深入剖析了PHP应用在Docker容器中运行异常的四大核心痛点——端口无法访问、文件挂载失效、php.ini或扩展未加载、PHP进程启动即退出，并逐一给出精准、可落地的排查逻辑与实操方案：从强制监听0.0.0.0、正确使用-p映射、验证docker ps的PORTS输出，到用docker exec直查挂载内容、谨慎挂载配置文件、确保前台阻塞式启动，再到推荐“先COPY再增量加挂载”的渐进调试法，帮你绕过90%的隐性坑，真正实现PHP容器一次跑通、稳定可用。

检查 docker run 是否漏掉 -p 或端口映射错误

PHP 服务在容器里启动成功但宿主机访问不到，大概率是端口没映射或映射错位。Docker 默认不暴露任何端口，EXPOSE 只是声明，不起实际作用。

实操建议：

• 确认 PHP 应用监听的是哪个端口（比如 php -S 0.0.0.0:8000，不是 127.0.0.1:8000）
• 运行容器时必须显式加 -p 8000:8000；若宿主机 8000 已被占用，可改用 -p 8080:8000
• 检查是否误写成 -p 8000:80——容器内没开 80 端口，自然连不上
• 用 docker ps 查看 PORTS 列，确认映射关系存在且格式为 0.0.0.0:8080->8000/tcp

验证文件挂载路径是否真实生效（特别是 ./src:/var/www/html 类映射）

代码改了但页面没更新，或者 require 报 No such file，往往不是代码问题，而是挂载根本没生效或路径错位。

实操建议：

• 进入容器：docker exec -it sh，然后 ls -l /var/www/html，看列出的文件是否和宿主机 ./src 下一致
• 注意路径是否用了绝对路径：宿主机写 $(pwd)/src 比 ./src 更可靠，尤其在脚本中执行时
• Windows/macOS 用户需确认 Docker Desktop 的文件共享设置已启用对应目录（如 macOS 要勾选 /Users，Windows 要授权 C:\）
• Linux 下若用 rootless Docker，挂载可能因权限被拒绝，尝试加 :z 或 :Z 标签（如 -v ./src:/var/www/html:z）

排查 php.ini 或扩展未加载：挂载覆盖了容器内配置

容器启动后 phpinfo() 显示的配置路径、扩展列表和预期不符，常见于把宿主机整个 php/conf.d/ 目录挂载进去，结果覆盖了基础配置或缺失关键 ini 文件。

实操建议：

• 不要直接挂载整个 conf.d 目录；优先用 docker cp 或构建镜像时 COPY 单个 ini 文件
• 若必须挂载，先进容器查清原路径：php --ini 输出 Loaded Configuration File 和 Scan for additional .ini files 路径
• 挂载单个文件时注意语法：-v $(pwd)/custom.ini:/usr/local/etc/php/conf.d/custom.ini:ro，末尾 :ro 防误写
• 挂载后执行 docker exec php -m 看扩展是否加载，比刷网页更快定位问题

确认 PHP 进程是否真在容器里跑着，而不是启动即退出

docker ps 看不到容器，或 docker logs 一闪而过就停，说明 PHP 启动命令没“驻留”。常见于用 php -S 但没加前台运行逻辑，或入口脚本执行完就 exit。

实操建议：

• 避免在 ENTRYPOINT 或 command 中写 php -S ... &——后台进程会被 Docker 当成主进程退出
• 确保启动命令是前台阻塞式：例如 php -S 0.0.0.0:8000 -t /var/www/html，不能漏 -t 或路径错
• 若用 supervisor 或自定义 shell 脚本，检查最后一条命令是否带 exec（如 exec php -S ...），否则 shell 退出容器就停
• 临时调试可加 tail -f /dev/null 卡住容器，再进容器手动起 PHP，快速验证环境是否 OK

挂载和端口看着简单，但路径层级、用户 UID、SELinux 标签、Docker Desktop 共享机制这些细节一碰就报错。最省事的方式是先不用挂载，把代码 COPY 进镜像，确认能跑；再一层层加挂载和端口，每步 docker exec 进去验证，比瞎猜快得多。

文中关于的知识介绍，希望对你的学习有所帮助！若是受益匪浅，那就动动鼠标收藏这篇《PHP源码Docker运行异常排查指南》文章吧，也可关注golang学习网公众号了解相关技术文章。