ThinkPHP Docker部署报错多为环境语义错位或配置疏漏所致，需分四类排查：一是MySQL连接问题，查Threads_connected与max_connections比值及日志中的“gone away”或“1040”错误，修正hostname为容器名、启用deploy=1、补全PDO超时与重连参数；二是runtime目录权限不足，需在Dockerfile中显式创建并赋777权限，且挂载方式设为rw；三是Class not found，确认composer install在构建阶段完成、入口文件引入autoload.php、OPcache已启用；四是Nginx 502或路由失效，检查PHP-FPM监听端口与fastcgi_pass配置是否匹配容器内地址。
ThinkPHP 在 Docker 中部署报错，多数不是代码问题，而是环境语义错位或配置疏漏导致的“假性故障”。核心要分清三类典型错误：连接池耗尽、权限拒绝、类找不到——每种背后都有明确路径可查。
一、MySQL 连不上：“too many connections” 或 “gone away”
这不是数据库扛不住，是 ThinkPHP 模型层在容器里反复建连、不复用、也不释放。
- 先进容器查真实连接数：mysql -h mysql -u root -p -e "SHOW STATUS LIKE 'Threads_connected';"（注意 host 必须填 数据库服务名，如
mysql，不能写127.0.0.1） - 若
Threads_connected接近max_connections（比如 148/150），才是真耗尽；若只有 20 却连不上，大概率是 PDO 根本没通 - 看日志：
tail -n 50 runtime/log/*.log | grep -i "gone\|1040"，高频出现 MySQL server has gone away，说明是wait_timeout导致的断连，不是数量问题 - 修复重点：
✓ 把config/database.php中'hostname' => 'localhost'改成'hostname' => 'mysql'
✓ 加上'deploy' => 1（必须是整数 1，不是true或'1'）
✓ 在'params'里补全三项：PDO::ATTR_TIMEOUT => 5、PDO::MYSQL_ATTR_INIT_COMMAND => "SET NAMES utf8mb4"、'break_reconnect' => true
二、runtime 目录写不进：Permission denied
访问空白页、日志里一堆 failed to open stream，90% 是权限没对齐，不是代码没写对。
- Dockerfile 中显式创建并赋宽松权限：
RUN mkdir -p /var/www/runtime/{log,cache,route,view} && chmod -R 777 /var/www/runtime - docker-compose.yml 里别挂整个项目目录，改用只读 + 独立挂载：
volumes: - ./app:/var/www:ro - ./runtime:/var/www/runtime:rw - 确认 PHP-FPM 配置里的
user和group与容器实际用户一致（常见坑：镜像用www-data，但你自定义了用户却没同步改 fpm）
三、Class 'think\App' not found
不是框架坏了，是自动加载根本没生效。
立即学习“PHP免费学习笔记（深入）”；
- 检查 Dockerfile 是否在
COPY . /var/www之后执行了：composer install --no-dev --optimize-autoloader - 确认入口文件
public/index.php包含：require __DIR__.'/../vendor/autoload.php'; - 别在容器启动时动态跑
composer install——构建阶段就得定死依赖 - 进容器执行：
php -m | grep opcache，确保 OPcache 已启用，否则 autoload 性能极差
四、Nginx 返回 502 或路由失效
本质是 PHP-FPM 没接住请求，或 Apache/Nginx 没正确转发。
- 查 PHP-FPM 容器是否监听对端口：进容器运行
netstat -tlnp | grep php-fpm，看它实际监听的是9000还是9003 - Nginx 配置中
fastcgi_pass必须指向 PHP-FPM 容器内端口（如php-fpm:9000），不是宿主机映射端口 - Apache 用户需启用重写：
RUN a2enmod rewrite，并在虚拟主机配置中设AllowOverride All
