PHP与MySQL连接失败时，应先检查mysqld进程是否运行、PHP是否加载mysqli/pdo_mysql扩展、host值是否适配（localhost/127.0.0.1/服务名）、用户认证插件兼容性（如caching_sha2_password需PHP 7.4+），再统一管理配置、区分三层超时、验证Docker网络连通性。
PHP 与 MySQL 连接失败时怎么快速定位
绝大多数“环境搭好了但连不上数据库”的问题，根源不在代码，而在连接参数或服务状态。先别急着改 mysqli_connect()，按顺序检查这几点：
- 确认
mysqld进程是否真在运行：sudo systemctl status mysql（Ubuntu/Debian）或sudo systemctl status mariadb（CentOS/RHEL） - 检查 PHP 是否加载了
mysqli或pdo_mysql扩展：运行php -m | grep mysql，没输出说明扩展未启用 -
host值别硬写localhost—— 它在部分系统下会走 Unix socket，而容器或远程 DB 需用127.0.0.1；Docker 场景必须用服务名（如mysql） - 用户权限不是只看用户名密码：MySQL 8+ 默认用
caching_sha2_password插件，PHP 7.4 以下版本不兼容，需建用户时显式指定mysql_native_password
配置文件里数据库参数怎么统一管理
多个 PHP 源码共用一套数据库时，最怕 config.php 各自为政。别复制粘贴，用常量 + 单点加载控制：
- 在 Web 根目录外建一个
/config/db.php（不在 Web 可访问路径），内容只含return ['host' => '127.0.0.1', 'dbname' => 'myapp']; - 所有源码入口（如
index.php）开头统一require_once __DIR__ . '/../config/db.php'; - 避免在
config.php里直接调用mysqli_connect()—— 连接应延迟到真正需要时，否则一启动就失败会阻塞整个流程 - 生产环境务必禁用
display_errors，但保留log_errors，错误日志路径要明确指向可写位置（如/var/log/php/error.log）
Nginx + PHP-FPM 下数据库连接超时怎么调
页面卡住、504 Gateway Timeout，往往不是 MySQL 慢，而是 PHP-FPM 等不到响应。关键要分清三层超时：
- PHP 层：
mysqli_connect()的第 5 个参数是连接超时（秒），默认 0（无限），建议设为5；查询超时用mysqli_options($link, MYSQLI_OPT_CONNECT_TIMEOUT, 5) - PHP-FPM 层：检查
/etc/php/{version}/fpm/pool.d/www.conf中的request_terminate_timeout（默认 0，即不限制），设为30s更稳妥 - Nginx 层：
fastcgi_read_timeout必须 ≥ PHP-FPM 的request_terminate_timeout，否则 Nginx 先断连，报错是upstream timed out - 别忽略 MySQL 自身的
wait_timeout（默认 28800 秒），短连接场景下它影响不大，但长连接池复用时，值太小会导致连接被服务端主动断开
Docker 环境中 PHP 和 MySQL 网络不通怎么办
Docker 不是把两个镜像 run 起来就能通的，网络隔离是默认行为。常见错误是直接用 127.0.0.1 访问宿主机 MySQL —— 容器里这地址指向自己，不是宿主机。
立即学习“PHP免费学习笔记（深入）”；
- 同一
docker-compose.yml里，PHP 服务要通过服务名访问 MySQL：比如host: mysql，前提是depends_on已声明且网络已共享（默认 bridge 网络自动完成） - 如果 PHP 容器需访问宿主机 MySQL（开发调试用），Linux/macOS 下用
host.docker.internal；Windows WSL2 需额外配置，不能依赖127.0.0.1 - MySQL 容器必须显式暴露端口（
ports: ["3306:3306"]）且绑定到0.0.0.0，否则仅监听127.0.0.1，外部容器无法连入 - 验证连通性别只靠
ping—— MySQL 不响应 ICMP，要用nc -zv mysql 3306或在 PHP 容器里执行php -r "var_dump(@mysqli_connect('mysql', 'user', 'pass', 'db'));"
真正的协同不是让 PHP 和 MySQL 都跑起来，而是让它们在各自生命周期内稳定交换数据。最容易被跳过的环节是：MySQL 用户权限的 host 字段（% vs localhost）、PHP 扩展是否真加载、以及 Docker 网络模式下的 DNS 解析行为。这些地方一错，前面所有配置都白搭。
