ThinkPHP Docker 部署必须将 Web 根目录设为 public，挂载时仅映射 public 目录到 /var/www/html，runtime 等敏感目录需单独挂载并确保 www-data 写权限；.env 必须运行时注入且置于项目根目录；多容器场景下 runtime 需隔离，避免缓存、日志、进程文件冲突。
容器里 public 目录必须是 Web 服务器根目录
ThinkPHP 默认靠 public/index.php 入口启动，Nginx/Apache 必须把 DocumentRoot 指向 public，否则路由失效、静态资源 404、__ROOT__ 路径错乱。Docker 里常见错误是直接挂载整个项目根目录到 /var/www/html，结果 Web 服务暴露了 app/、runtime/ 等敏感目录。
- 挂载时只映射
public目录：用-v $(pwd)/public:/var/www/html，而非-v $(pwd):/var/www/html -
runtime、config、extend这些非公开目录，通过另一条-v单独挂载，路径与容器内应用结构对齐（例如-v $(pwd)/runtime:/var/www/runtime） - 确保容器内 PHP 进程用户（如
www-data）对runtime和log目录有写权限，否则mkdir(): Permission denied错误会静默失败
.env 文件不能硬编码进镜像，得运行时注入
本地开发的 .env 含数据库密码、密钥等，打进镜像等于泄露凭证。Docker Compose 或 Kubernetes 中应通过 env_file 或 secrets 注入，且需确认 ThinkPHP 是否加载成功——它默认只读取项目根目录下的 .env，而你挂载的 public 是子目录，根目录可能已不可写或不包含该文件。
- 在
Dockerfile中保留项目根目录（如/var/www），仅把public作为 Web 根；.env放在/var/www/.env，再挂载覆盖 - 验证是否生效：在容器里执行
php think env:show（需安装 think-command 插件）或打印Env::get('database.hostname') - 如果用
docker run -e DB_HOST=xxx方式传环境变量，需在.env中用DB_HOST=${DB_HOST}语法，并确保 PHP 的putenv()可用（某些 Alpine 镜像默认禁用）
runtime 目录挂载后要注意清空策略和 SELinux 上下文
容器重启时，若宿主机挂载的 runtime 目录残留旧缓存（如 cache/ 下的 opcode 或模板编译文件），可能导致路由解析异常、配置未更新、甚至 Class not found。更隐蔽的问题是 SELinux（如 CentOS 主机）会阻止容器进程写入挂载目录，报错类似 failed to open stream: Permission denied，但日志里不提示 SELinux。
- 启动容器前手动清空
runtime：用rm -rf runtime/*，或在entrypoint.sh中加rm -rf /var/www/runtime/{cache,log,route,session} - 挂载时加
:z或:Z标签（如-v $(pwd)/runtime:/var/www/runtime:z），让 Docker 自动处理 SELinux 上下文 - 避免把
runtime挂到 NFS 或远程卷——ThinkPHP 的文件锁（flock）在分布式文件系统上不可靠，缓存可能错乱
多容器协作时，think queue:work 进程不能和 Web 服务共用同一份 runtime
Web 容器和队列容器如果都挂载同一个 runtime 目录，会出现 queue.pid 冲突、日志混写、缓存键碰撞等问题。尤其当队列进程修改了 cache/ 下的配置缓存，Web 进程却还在用旧的 APCu 或 OPcache，行为就不可预测。
立即学习“PHP免费学习笔记（深入）”；
- 为队列单独准备挂载路径：
-v $(pwd)/runtime-queue:/var/www/runtime，并在docker-compose.yml中用不同environment区分角色 - 队列容器启动命令显式指定运行模式：
php think queue:work --daemon --sleep=3 --max-jobs=1000，避免因共享 runtime 导致--once模式反复重载失败 - 检查
config/queue.php中的default驱动是否与实际部署一致（Redis 在容器里地址是redis:6379，不是127.0.0.1）
最麻烦的其实是 runtime 权限和挂载时机——宿主机目录不存在时 Docker 会自动创建，但创建者是 root，容器里 www-data 就写不了；挂载发生在容器启动前，但目录初始化逻辑（比如首次生成 runtime/log）又依赖 PHP 进程，这个顺序得人工兜住。
