升级phpMyAdmin需先停用旧版服务，清空浏览器缓存与OPcache，谨慎迁移config.inc.php并校验配置项、PHP版本、扩展依赖及themes/plugins目录。
直接覆盖升级前必须停用旧版服务
phpmyadmin 是纯 php 应用，没有后台进程，但浏览器可能缓存旧 js/css 或会话残留导致界面错乱、sql 执行异常。升级不是复制粘贴完就完事，得先清空用户侧干扰。
- 关闭所有已打开的 phpMyAdmin 页面，尤其注意标签页里挂着的
index.php或tbl_sql.php等子页面 - 清空浏览器缓存（或强制硬刷新：
Ctrl+Shift+R），否则可能加载旧版navigation.js导致左侧数据库列表不刷新 - 如果用了 PHP 的 OPcache，执行
opcache_reset()或重启 Web 服务（如sudo systemctl restart apache2），否则新代码可能不生效
配置文件 config.inc.php 不能直接覆盖
新版 phpMyAdmin 的默认配置结构和加密方式有变化，比如 $cfg['blowfish_secret'] 长度要求更严格，$cfg['Servers'][$i]['auth_type'] 的可选值也新增了 signon。直接覆盖会导致登录白屏或报错 The configuration file now needs a secret passphrase (blowfish_secret)。
- 保留旧版
config.inc.php，只把新版里的config.sample.inc.php当参考，逐项比对新增/变更项（如$cfg['TempDir']路径是否仍有效） - 特别检查
$cfg['Servers'][$i]['host']和$cfg['Servers'][$i]['port']—— 新版默认不再自动 fallback 到localhost:3306，填错会提示mysqli_real_connect(): (HY000/2002) - 若启用了
$cfg['LoginCookieValidity']，新版单位已改为秒，旧值（如3600）仍可用，但别误写成3600000（毫秒）导致 Cookie 瞬间过期
升级后访问 index.php 报 500 错误？先查 PHP 版本兼容性
phpMyAdmin 5.2+ 要求 PHP ≥ 7.2.5，5.3+ 要求 ≥ 8.0；低于版本会直接 500，且错误日志里可能只显示 PHP Parse error: syntax error, unexpected token "string" 这类模糊提示。
- 运行
php -v确认当前 CLI 版本，再查 Web 服务用的 PHP SAPI（如 Apache 模块 or FPM）是否一致：phpinfo()页面里的Server API行 - 新版依赖
mbstring、openssl、json、zip扩展，缺任一都会在index.php报 500；用php -m | grep -E 'mbstring|openssl|json|zip'快速筛查 - 若用的是 Debian/Ubuntu，别只升级 phpMyAdmin 包，还要确认
php-mbstring等扩展包已随 PHP 版本同步更新，否则 apt 安装的新版 phpMyAdmin 会因扩展版本太老而崩
用户自定义主题和插件要手动迁移
phpMyAdmin 的 themes/ 和 plugins/ 目录不在 git clone 或 tar 包里，默认是空的。如果你之前加过自定义主题（比如深色主题）或导出插件（如 Excel 导出），覆盖升级时这些文件不会被保留，但旧配置里又引用了它们，结果就是界面错位或功能按钮消失。
- 升级前备份整个
themes/和plugins/目录（不要只备份单个子目录） - 新版目录结构可能微调：比如 5.2+ 把
js/vendor/移到了js/dist/，如果你的主题里写了硬路径../js/vendor/jquery.min.js，就得改成相对新版结构的写法 - 插件启用需在
config.inc.php显式声明，例如启用export_templates插件，要加一行：$cfg['Plugins']['export']['templates'] = true;，光放文件没用
