phpMyAdmin 官方不支持真正主题系统，仅提供基于CSS变量的明暗模式微调；所谓“主题”实为预编译CSS文件，强行套用第三方主题易致界面错乱或白屏。
phpmyadmin 官方不支持“安装主题包”这种操作，所谓“全新主题”基本是第三方魔改版或旧版本遗留概念；当前稳定版（5.2+）只允许微调 css 变量或替换少数皮肤文件，强行套用非官方主题极易导致界面错乱、ajax 失败甚至登录页白屏。
为什么 phpMyAdmin 没有真正的主题系统
它不是 WordPress 或 VS Code —— 没有主题注册机制、不加载外部 theme.php、也不扫描 themes/ 目录。所谓“主题”，实际只是几组预编译的 CSS 文件 + 少量图标替换，由 $cfg['ThemePath'] 和 $cfg['ThemeDefault'] 控制加载路径和默认值。5.0 之后连 themes/ 目录都默认移除了。
- 官方明确声明：主题仅用于“视觉微调”，不改变结构或行为
- 所有“一键换肤”脚本本质是覆盖
./css/phpmyadmin.css或注入自定义style标签 - 使用非官方 CSS 时，
table tr:nth-child(even)这类选择器极易因新版 HTML 结构变化而失效
如何安全地更换浅色/深色外观（官方唯一支持方式）
phpMyAdmin 5.2+ 内置了基于 CSS 变量的明暗模式切换，这是唯一不会破坏功能的视觉调整途径。
- 确保
$cfg['ThemePath']未被手动修改（默认为''，即禁用外部主题） - 在
config.inc.php中添加：$cfg['DarkMode'] = 'auto'; // 或 'light' / 'dark'
- 若想自定义颜色，直接编辑
./css/themes.css中的:root变量块，例如修改--pmahomestyle-bg - 切勿删除或重命名
./css/common.css—— 它包含表单、弹窗等关键样式规则
如果坚持要用第三方 CSS 主题（风险自担）
常见错误是把 GitHub 上标着 “phpMyAdmin Theme” 的仓库整个解压进 ./themes/，结果发现 index.php 报 Undefined index: ThemePath 或登录后空白。
- 必须确认该主题是否适配你的 phpMyAdmin 版本（查
composer.json或 README 中的requires字段） - 不要复制整个仓库，只提取
css/下的theme.css（或类似命名），然后通过$cfg['AdditionalJSFiles']注入，而非替换原生 CSS - 禁用浏览器缓存调试：
Ctrl+F5并检查开发者工具中Network标签页是否 404 加载了theme.js等不存在的资源 - 最常崩的位置是
navigation panel和sql query box—— 它们的 DOM 结构在 5.1 和 5.2 之间变动过两次
配置生效后仍显示旧样式的排查点
不是配置没写对，而是缓存或路径优先级在捣鬼。
立即学习“PHP免费学习笔记（深入）”；
- 检查
./config.inc.php是否被多个地方加载（比如 Nginx 的fastcgi_param PHP_VALUE会覆盖文件内设置） - 运行
php ./libraries/classes/Util.php --check-theme（如存在）—— 实际上官方没提供这个命令，纯属误导；正确做法是查看响应头中的X-PhpMyAdmin-Theme是否出现 - 清空浏览器中
https://your-pma.example.com/域下的所有 Cookie 和存储（特别是pma_theme这个 localStorage key） - 临时将
$cfg['TempDir']指向一个空目录，排除缓存 CSS 被复用的可能
真正麻烦的从来不是换颜色，而是某天升级后发现深色模式下 SQL 编辑器的光标看不见、或者右键菜单文字全叠在一起——这时候你得打开开发者工具，一行行比对 computed style，而不是重装主题包。
