ThemeManager加载失败时典型现象为白屏或“Failed to load theme”，控制台报realpath()警告且themes路径反复出现；主因是$cfg['ThemePath']或$cfg['ThemeDefault']配置错误或缺失layout.inc.php文件；修复需三步：删除config.inc.php中这两行配置、清理损坏主题目录、清空tmp/并重启PHP-FPM。
ThemeManager加载失败时的典型报错现象
打开 phpMyAdmin 页面直接白屏，或报 Failed to load theme；控制台看到 realpath(): Passing null to parameter #1 警告；./themes/metro/ 或其他主题路径在错误堆栈中反复出现。这些都指向 ThemeManager 初始化阶段读取主题配置失败，常见于手动修改过 config.inc.php 中的 $cfg['ThemePath']、$cfg['ThemeDefault']，或误删了 themes/ 下某个主题的 layout.inc.php 文件。
重置 ThemeManager 配置的三步实操
不需要重装 phpMyAdmin，只需定位并清理两处关键配置：
-
$cfg['ThemePath']和$cfg['ThemeDefault']若被显式设为不存在的路径或空字符串，会强制 ThemeManager 加载失败 —— 直接从config.inc.php中删除这两行（不是注释掉，是彻底移除） - 检查
themes/目录下是否残留损坏主题：进入themes/，确认每个子目录都包含layout.inc.php；若发现某个主题（如metro）目录里没有该文件，直接rm -rf themes/metro - 强制刷新 ThemeManager 缓存：删除
tmp/目录下的所有内容（rm -rf tmp/*），该目录通常位于 phpMyAdmin 根目录下；若使用 systemd 或 opcache，还需重启 PHP-FPM 服务
为什么不能只改 $cfg['ThemeDefault']？
单独设置 $cfg['ThemeDefault'] = 'pmahomme'; 是无效的，前提是 $cfg['ThemePath'] 没有同时指向正确的主题根路径。phpMyAdmin 5.2 的 ThemeManager 在初始化时会先拼接 $cfg['ThemePath'] . '/' . $cfg['ThemeDefault']，再调用 realpath() 检查路径有效性。一旦拼出的路径不存在，就立即抛出弃用警告并中断加载 —— 所以必须让这两个配置项回归默认行为（即不设值），由系统自动推导。
验证是否修复成功
访问 phpMyAdmin 后，在右下角点击「切换主题」按钮，应能正常列出所有可用主题（如 pmahomme、original），且切换后界面无错位、无 JS 报错。如果仍看到 Warning: realpath(): Passing null，说明仍有某处代码（比如自定义 config.header.inc.php）动态覆盖了 $cfg['ThemePath']，需全局搜索该变量赋值位置。
立即学习“PHP免费学习笔记（深入）”；
