ThinkPHP Docker化常见问题有四类：一是storage/runtime目录权限不足，需对齐UID/GID或镜像内初始化属主；二是TP_ENV/APP_DEBUG未透传，需在php-fpm或Nginx中显式声明；三是MySQL连接错用127.0.0.1，应改用服务名并授权远程访问；四是Nginx根目录未指向public导致静态资源404及路由异常。
挂载目录权限不足导致 storage 和 runtime 写入失败
ThinkPHP 启动时会往 storage 和 runtime 目录写日志、缓存、模板编译文件，Docker 容器默认以 www-data（或 apache）用户运行 PHP-FPM，但宿主机挂载进来的目录往往属于 root 或当前用户，容器内进程无权写入。
常见错误现象：file_put_contents(/var/www/html/runtime/log/202405/15.log): failed to open stream: Permission denied，或页面空白、500 错误且无日志输出。
- 在
docker-compose.yml中为 PHP 服务显式指定用户 UID/GID，与宿主机目录属主对齐（例如宿主机目录属主是1001:1001，则加user: "1001:1001"） - 更稳妥的做法：构建镜像时在
Dockerfile中创建同名用户并设为非 root（如useradd -u 1001 -m www），再用chown -R www:www /var/www/html/storage /var/www/html/runtime初始化目录权限 - 避免直接用
chmod 777宿主机目录——临时有效但破坏安全边界，上线环境不可行
TP_ENV 和 APP_DEBUG 环境变量未生效
ThinkPHP 依赖 TP_ENV（如 production）和 APP_DEBUG（0 或 1）控制配置加载路径和错误显示行为。Docker 中若仅靠 .env 文件，PHP-FPM 默认不自动加载它；而通过 environment 或 env_file 注入的变量，需确认是否被 Web 服务器（Nginx/Apache）透传给 PHP 进程。
典型表现：始终走 app.php 而非 app_production.php，或 APP_DEBUG=0 时仍显示详细错误堆栈。
立即学习“PHP免费学习笔记（深入）”；
- 在
php-fpm.conf或www.conf中显式声明要传递的变量，例如：env[TP_ENV] = production、env[APP_DEBUG] = 0 - 若用 Nginx，确保
fastcgi_param包含对应项，例如：fastcgi_param TP_ENV $TP_ENV;，并在server块中定义set $TP_ENV "production";或从环境读取（需 Nginx 1.19+ +env指令支持） - 验证方式：在控制器里打印
getenv('TP_ENV')或$_ENV['TP_ENV']，确认值存在且正确
MySQL 连接超时或拒绝访问：容器网络与 DB_HOST 配置错位
本地开发时 DB_HOST 常写 127.0.0.1 或 localhost，但在 Docker Compose 网络中，PHP 容器需通过服务名（如 mysql）访问数据库容器，而非宿主机回环地址。
错误现象：SQLSTATE[HY000] [2002] Connection refused，或连接成功但查询超时，日志里反复重试。
- 将
.env中的DB_HOST=mysql（对应docker-compose.yml里 service 名称），而非127.0.0.1或host.docker.internal（后者仅适用于 Mac/Windows，Linux 需手动配置） - 确保 MySQL 容器已启用远程访问：检查
my.cnf是否禁用了skip-networking，且用户授权包含'%'主机（如CREATE USER 'tp'@'%' IDENTIFIED BY 'xxx'; GRANT ALL ON tp_db.* TO 'tp'@'%';） - 启动顺序依赖：在
docker-compose.yml中为 PHP 服务加depends_on: [mysql]，并配合健康检查（healthcheck）避免 PHP 在 MySQL 尚未就绪时启动
静态资源 404：Nginx 根目录与 ThinkPHP 路由重写冲突
ThinkPHP 推荐部署在子目录（如 /public）下，Nginx 配置需将根目录指向 /var/www/html/public，否则 index.php 无法被正确路由，CSS/JS 也因路径错位返回 404。
典型症状：首页可访问但样式丢失、AJAX 请求 404、URL 中出现重复 public 路径。
- Nginx
root必须设为/var/www/html/public，不是项目根目录；同时确认容器内该路径真实存在（构建镜像时复制或挂载正确） - 重写规则必须匹配 ThinkPHP 的入口逻辑，标准写法：
try_files $uri $uri/ /index.php?$query_string;，不能漏掉$query_string，否则 GET 参数丢失 - 若使用 Apache，需确认
.htaccess已启用且AllowOverride All生效；Docker 中常因权限或模块未启用导致重写失效
ThinkPHP 迁移进 Docker 最容易卡在「权限」和「环境透传」两个环节——前者影响运行时写入，后者决定配置是否真正加载。别只盯着 PHP 报错，先确认 storage 目录在容器里能 touch，再查 getenv() 返回值，最后看 Nginx access log 里请求有没有被正确转发到 index.php。
