官方php:8.2-apache镜像已预装常用扩展并配置好Apache，直接挂载代码即可运行；定制时须注意扩展安装顺序、opcache显式启用、数据库连接用容器名而非localhost，且避免覆盖默认php.ini。
php:8.2-apache 镜像开箱即用，绝大多数场景下**不需要自己写 Dockerfile**；真要定制，核心是避免重装扩展、别覆盖默认配置、数据库连接必须用容器名。
为什么别急着写 Dockerfile？
官方 php:8.2-apache 镜像已预装 pdo_mysql、mbstring、curl、json 等常用扩展，Apache 服务也已配置好。直接挂载代码就能跑 Laravel、WordPress 或普通 index.php。
常见错误现象：
- 页面空白 → 没用
-v挂载代码，/var/www/html是空的 - 500 错误但无日志 → 扩展安装顺序错（比如
pdo_mysql在pdo前）或系统依赖缺失（如gd缺libpng-dev） - 连不上 MySQL → 连接字符串里写
localhost，实际该写容器名（如mysql）
必须写 Dockerfile 时的关键操作
只在需要启用未预装扩展（如 xdebug、redis）、调整 PHP 配置或集成特定构建步骤时才写。重点如下：
Docker Image Puller
下载
使用 Python 脚本下载 Docker 镜像并打包为 tar 文件。用户说“下载镜像”“拉取镜像”“pull xxx”“帮我下载 nginx 镜像”等时触发。支持 SOCKS5 代理直连（推荐）和国内镜像站加速两种模式。
-
RUN docker-php-ext-install必须按依赖顺序执行：先pdo，再pdo_mysql；装gd前先apt-get install libpng-dev libjpeg-dev -
opcache编译进 PHP 后默认不启用，需显式开启：RUN echo "opcache.enable=1" > /usr/local/etc/php/conf.d/opcache.ini - 别
COPY php.ini全量覆盖 —— 会丢掉镜像自带的date.timezone、upload_max_filesize等关键默认值；改配置优先走conf.d/下的独立文件 - Alpine 镜像中
date.timezone必须显式设置，否则DateTime构造会警告；推荐写成date.timezone = "Asia/Shanghai"
docker-compose.yml 中 PHP 连 MySQL 总失败？
不是配置写错了，是网络和启动逻辑没理清：
立即学习“PHP免费学习笔记（深入）”；
- PHP 容器内写
host=localhost或127.0.0.1必然失败 —— 这是它自己的回环地址，不是 MySQL 容器 - MySQL 服务名是
mysql，PHP 就得用mysql:host=mysql;dbname=test -
depends_on只控制启动顺序，不保证 MySQL 已 ready；加健康检查或应用层重试更可靠 - Alpine 镜像连 MySQL 8.0 常报 SSL 错误，因缺
libssl1.1；要么换debian基础镜像，要么手动apk add openssl
权限问题比想象中更常导致白屏
宿主机用户 UID 和容器内 www-data（UID 33）不一致时，composer install 或 Laravel storage 写入会失败：
- 临时解决：
docker run --user $(id -u):$(id -g)让进程以当前用户身份运行 - 长期方案：Dockerfile 中建新用户并设组权限，例如
RUN useradd -u 1001 -m app && usermod -a -G www-data app - 别在 Dockerfile 里
RUN chown -R www-data:www-data /var/www/html—— 官方镜像已预设权限，重复操作反而破坏挂载卷权限
php -i | grep 'Loaded Configuration File'，而要用 php -m 确认扩展列表，用 php --ini 检查 conf.d/ 路径是否在扫描范围内。 
