无损升级phpMyAdmin需同时满足路径、权限、PHP兼容性三者匹配，否则将出现空白页、500错误或扩展缺失报错；不同安装方式对应不同升级路径，须严格区分并保留config.inc.php关键配置项。
直接覆盖旧文件 + 保留 config.inc.php 就能无损升级，但前提是路径、权限、php 兼容性三者都对得上——漏掉任意一个，就会出现空白页、500 错误或“缺少 mysqli 扩展”这类报错。
确认当前安装方式和路径再动手
不同安装方式对应完全不同的升级路径，混用会导致配置丢失或服务不可用：
- 用
apt（Ubuntu/Debian）或yum（CentOS）装的：优先走包管理器升级，/usr/share/phpmyadmin/是主目录，/etc/phpmyadmin/config.inc.php是真实生效配置 - 手动解压到
/var/www/html/phpmyadmin/或/htdocs/phpmyadmin/的：必须原地覆盖，且要确保新版本解压后文件夹名一致（比如不能是phpMyAdmin-5.2.1-all-languages，得重命名为phpmyadmin） - phpStudy Pro、XAMPP 等集成环境：路径固定（如 phpStudy 是
PHPServer\phpmyadmin），删旧文件夹 → 粘贴新解压内容 → 不要改名
执行前先运行 find / -name "phpmyadmin" -type d 2>/dev/null 定位真实路径，比凭记忆操作可靠得多。
config.inc.php 怎么保留才真正“无损”
很多人备份了 config.inc.php 却升级后仍要重配，问题出在两个细节：
- 新版 phpMyAdmin 可能新增必需配置项（如
$cfg['TempDir']或$cfg['blowfish_secret']），直接复用旧文件会报“配置文件现在需要一个短语密码” - 路径写死的配置（如
$cfg['Servers'][$i]['host'] = '127.0.0.1';）在容器或远程 DB 场景下可能失效，需核对 - 若旧版用了自定义
blowfish_secret，复制时务必保留；若没设过，新版首次访问 setup 页面会生成，但该页面默认禁用，需临时放开$cfg['Servers'][$i]['auth_type'] = 'cookie';并确保/usr/share/phpmyadmin/setup/有 Web 写入权限
推荐做法：把旧 config.inc.php 复制到新目录后，用 diff 对比新版自带的 config.sample.inc.php，只补缺关键项，不全盘覆盖。
立即学习“PHP免费学习笔记（深入）”；
PHP 版本和扩展兼容性必须提前验证
phpMyAdmin 5.2+ 要求 PHP ≥ 7.4，且强制依赖 mysqli 和 mbstring；5.3+ 已不再支持 PHP 7.x。常见报错直接指向这里：
-
PHP 5.3+ is required→ 实际是 PHP 版本太低，不是 phpMyAdmin 问题；降级 phpMyAdmin（如用 4.9.x）只是权宜之计 -
缺少 mysqli 扩展→ 检查php -m | grep mysqli，确认extension=mysqli在php.ini中已启用，且不是被extension_dir路径错误导致加载失败 - 升级后首页空白 → 开启
display_errors = On和error_reporting = E_ALL，看 PHP 错误日志里是否报Failed to load extension 'mbstring'
Debian 11/12 用户尤其注意：默认源的 phpMyAdmin（5.0.4）不兼容 PHP 8.1+，必须添加 Ondřej Surý 仓库，否则硬覆盖新版二进制文件会因符号链接断裂或 SELinux 上下文丢失而失败。
权限和 SELinux 容易被忽略的点
覆盖后 Apache/Nginx 进程读不到文件，是最隐蔽的“无损”失败原因：
- CentOS/RHEL：新目录需
chown -R apache:apache /usr/share/phpmyadmin（Apache）或nginx:nginx（Nginx） - SELinux 启用时，仅改属组不够，还得恢复上下文：
restorecon -Rv /usr/share/phpmyadmin - Ubuntu/Debian：确保
www-data对整个目录有r-x权限，特别留意tmp/和libraries/vendor/子目录，新版依赖 Composer 自动加载，权限不足会静默失败
升级完别急着关终端，先用 curl -I http://localhost/phpmyadmin/ 看返回状态码——200 且 Content-Type: text/html 才算真正就绪；302 重定向或 500 都意味着某个环节卡住了。
