FrankenPHP数据库连接失败主因是运行模式改变连接上下文：HTTP Server/Swoole常驻进程导致环境变量未透传、.env未加载、PDO连接复用超时或MySQL认证插件不兼容，需针对性排查环境、连接释放与DSN配置。
FrankenPHP 启动后 PHP 脚本连不上数据库，**90% 不是 FrankenPHP 本身的问题，而是它运行在 Swoole 或 HTTP Server 模式下改变了连接上下文**——比如长生命周期导致连接复用、环境变量未透传、或默认不加载 .env 文件。别急着重装，先按真实故障链路排查。
FrankenPHP 的 CLI 模式 vs HTTP Server 模式对数据库连接的影响
FrankenPHP 有两种主要运行方式：frankenphp serve（开发用 HTTP Server）和 frankenphp worker（生产用 Swoole Worker）。两者关键差异在于：
-
frankenphp serve会模拟传统 PHP-FPM 行为，但每次请求仍共享同一个进程，$_ENV和getenv()可能被缓存，修改.env后需重启命令才能生效 -
frankenphp worker是常驻进程，PHP 生命周期长达数小时，PDO连接若没显式关闭或复用不当，会触发 MySQL 的max_connections耗尽或服务端主动断连（尤其云数据库 wait_timeout=300 秒很常见） - 两种模式默认都不自动加载
.env——Laravel 的Dotenv::createImmutable()必须显式调用，否则DB_HOST等全是空字符串
环境变量没透传到 FrankenPHP 进程里
FrankenPHP 不继承 shell 的全部环境变量，尤其是通过 systemd 或 Docker 启动时，DB_PASSWORD 含 @、/、: 等字符时极易被截断或解析失败。
- 验证方法：在 PHP 脚本开头加
var_dump($_SERVER['DB_HOST'] ?? 'not set', $_ENV['DB_HOST'] ?? 'not set');，看是否为空 - Docker 中必须用
environment:显式声明，不能只靠.env文件；Docker Compose 示例片段：services: app: image: dunglas/frankenphp environment: - DB_HOST=db - DB_PORT=3306 - DB_USER=root - DB_PASSWORD=pass@word/123 # 这里要 URL 编码？不，直接写，但启动前用 echo $DB_PASSWORD 测是否被 shell 吃掉 - Linux systemd 服务中，需在
.service文件里写Environment="DB_PASSWORD=pass@word/123"，双引号不能省，否则@被当邮箱解析
PDO 连接未设超时或未释放，导致“隔几分钟就 Connection refused”
这是 FrankenPHP 最典型的“伪连接失败”：第一次请求成功，之后报 SQLSTATE[HY000] [2002] Connection refused，其实不是连不上，是上次的连接被 MySQL 主动断开了，而 FrankenPHP 还拿着失效句柄复用。
立即学习“PHP免费学习笔记（深入）”；
- PDO DSN 必须加
connect_timeout=5和timeout=5，例如：mysql:host=$host;port=$port;dbname=$db;charset=utf8mb4;connect_timeout=5;timeout=5 - 务必在
try/catch后加$pdo = null;，不要依赖脚本结束自动释放——FrankenPHP 进程不死，连接就不关 - 检查 MySQL 实际连接数：
mysql -e "SHOW STATUS LIKE 'Threads_connected';"，持续 > 100 就说明连接泄漏了 - 云数据库（如阿里云 RDS、AWS RDS）默认
wait_timeout=300，必须配PDO::ATTR_TIMEOUT或在 DSN 里写死connect_timeout，否则复用旧连接必炸
MySQL 8+ caching_sha2_password 认证插件不兼容
FrankenPHP 默认用系统 PHP（可能是 8.2+），但若你连的是老 MySQL 5.7 或新 MySQL 8.0+ 且用户用了默认认证插件，PDO 会静默失败，错误信息却是模糊的 SQLSTATE[HY000] [2054]。
- 快速验证：在 FrankenPHP 容器/服务器里执行
php -r "new PDO('mysql:host=localhost;dbname=test', 'user', 'pass');"，看是否抛出该错误 - 临时修复（开发）：进 MySQL 执行
ALTER USER 'your_user'@'%' IDENTIFIED WITH mysql_native_password BY 'your_pass'; FLUSH PRIVILEGES; - 长期方案：确认
php -m | grep pdo_mysql有输出，且 PHP ≥ 7.4；若用 Alpine 镜像，确保安装了php82-pdo_mysql（版本号必须匹配）
最易被忽略的一点：FrankenPHP 的 frankenphp serve 默认监听 localhost:8000，但如果你的数据库配置写的是 DB_HOST=127.0.0.1，在 Docker 网络里这俩根本不是一回事——localhost 指容器自身，127.0.0.1 是宿主机回环，而数据库服务通常在另一个容器里，必须用服务名（如 db）或宿主机网关 IP（如 172.17.0.1）。
