phpMyAdmin 配置中 port 字段被忽略的根本原因与正确配置方法

在 Docker 环境中用 phpMyAdmin 连接 MySQL 时，一个极其常见的困惑是：明明在配置文件里明明白白地设置了 port 字段，可登录页就是告诉你连不上。这事儿折腾过不少人，今天咱们就把这个“幽灵问题”彻底拆开看看。

先说几个核心判断：这并不是 phpMyAdmin 的 Bug，而是它的连接机制在设计上就有个小脾气——它不会自动把 port 字段里的值拼到 host 后面去用。这事儿听起来有点反直觉，但理解了它的逻辑，一切就都顺了。

核心原理：host 与 port 到底怎么协作？

phpMyAdmin 底层怎么决定连到哪个 MySQL 实例？这主要看三个字段的配合：

• host：决定目标，可以是域名、IP 或者 localhost。
• connect_type：决定通信协议走 tcp 还是 socket。
• port：这个字段有个关键前提——只有当你把 connect_type 显式设为 tcp，并且 host 里没有冒号时，它才会真正发挥作用。

那问题出在哪儿呢？很多人直接在 host 里写了 'localhost:3306'，然后又保留了 port = 3306。这时候 phpMyAdmin 会直接拿 host 里的完整字符串去建立 TCP 连接，完全无视 port 字段。更糟糕的是，它不会报错说“我不用你的 port”，而是默默地在界面或者日志里给你显示 localhost:3306:3306——端口重复了，连接自然失败。

简单记一句话：host 是“完整地址”，port 是“备用端口”——回到根上，它俩是互斥的，不能共存。

正确配置方案，二选一

既然知道了问题根源，解决方案就很清晰了。

方案一：纯 host + 显式 connect_type + port（推荐）

这种做法适合需要统一管理配置、或者通过变量注入端口号的场景。

$cfg['Servers'][$i]['host'] = 'localhost';           // 不带端口！
$cfg['Servers'][$i]['connect_type'] = 'tcp';         // 强制走 TCP
$cfg['Servers'][$i]['port'] = 3306;                  // 此时 port 生效
$cfg['Servers'][$i]['extension'] = 'mysqli';

这样配置，语义清楚，以后改端口只改一个变量就行，不容易出错。但要警惕：host 里绝对不能出现冒号，否则 port 会被静默忽略。

方案二：host 直接携带端口

如果你追求直觉式的写法，觉得“地址就该是一个整体”，那也可以这样：

$cfg['Servers'][$i]['host'] = 'localhost:3306';      // 完整地址，port 字段废弃
// $cfg['Servers'][$i]['port'] = 3306;              // ← 一定要注释或删掉！
$cfg['Servers'][$i]['connect_type'] = 'tcp';         // 建议显式声明

这种做法的好处是直观，但一旦你在其他地方（比如 config-db.php）定义了 $dbport，又用 "{$dbserver}:{$dbport}" 拼接了 host，还顺手把 $dbport 赋值给了 port 字段——那就等着端口重复吧。

Docker 场景下的特别提醒

很多人是在 Docker 里遇到这个问题的，比如你用 init.sh 创建了一个 'admin'@'localhost' 用户，并且用了 mysql_native_password 插件，这一步没错。但有一个隐蔽的坑：

MySQL 8.0+ 默认的认证插件是 caching_sha2_password，而 phpMyAdmin 4.9.5 根本不支持这个新插件。哪怕你的连接地址完全正确，它也会静默失败——没有明确的报错，只是提示“无法登录”。

解决办法是在初始化脚本里强制把 admin 用户的认证方式改回来：

mysql -u root -e "
  ALTER USER 'admin'@'localhost' IDENTIFIED WITH mysql_native_password BY 'admin';
  FLUSH PRIVILEGES;"

同时确认 config.inc.php 里启用了 mysqli 扩展（你已经做了），并且把 AllowNoPassword 关掉，除非你真的需要允许空密码登录。

常见陷阱一览

最终验证步骤

按下面的顺序走一遍，基本就能确认问题已经解决：

1. 修改 config.inc.php，采用方案一进行配置。
2. 重启容器：docker restart <容器名>。
3. 访问 http://localhost/phpmyadmin，用 admin / admin 登录。
4. 登录成功后，点击右上角 → 服务器：localhost:3306 —— 应该只显示一个端口，干净利落。
5. 进入「用户账户」页，确认可以正常查看和管理用户。如果这里报 #1146 错误，说明表结构有问题，需要回查 MySQL 版本兼容性。

配置这件事，一旦摸清了 phpMyAdmin 的性格，其实并不复杂。关键在于理解它“先看 host，再决定用不用 port”的逻辑，然后根据自己的部署方式，把二选一做到位。这样，Docker 环境下的数据库管理就能稳稳地跑起来。