phpMyAdmin主题加载失败因目录结构或theme.json配置错误导致静默回退至blue主题，如多层父目录、大小写不匹配、name字段与目录名不一致、compat_version未精确匹配主版本号，或CSS/字体路径权限不足、硬编码路径及多层缓存未清除。
主题包解压后目录结构不对，phpMyAdmin 直接跳过加载
phpMyAdmin 不会报错，也不会提示“主题无效”，它只默默回退到 blue 主题——因为主题包没放进正确位置，或目录名与 theme.json 里的 "name" 字段不一致。
常见错误包括：
- 把整个 zip 解压出来后，多了一层父文件夹（如
dracula-master/），实际应只保留themes/dracula/这一层 -
themes/dracula/theme.json中的"name": "Dracula"（首字母大写）但目录名是小写的dracula，Linux 系统下严格区分大小写 -
"name": "dracula-theme"但目录名是dracula，两者必须完全一致（连横杠、下划线都不能差）
theme.json 的 compat_version 填错，主题被静默忽略
这个字段不是“兼容最低版本”，而是“仅匹配该主版本号”。填 "5" 或 "5.2.1" 都不行，必须是当前 phpMyAdmin 的主版本号，例如你用的是 5.2.4，就得写 "5.2"。
查法很简单：登录 phpMyAdmin，右下角有小字显示版本号；或者打开 phpmyadmin/VERSION 文件看第一行。
立即学习“PHP免费学习笔记（深入）”；
如果填错，phpMyAdmin 在初始化时就跳过整个主题目录，不会写日志，也不会报错。
CSS 和字体文件路径权限或路径写死导致 404
即使主题目录和 theme.json 都对，浏览器仍加载默认样式，大概率是资源请求返回了 404 或 403。
验证方式直接在浏览器访问：
-
/phpmyadmin/themes/your-theme/css/theme.css→ 应返回 CSS 内容（HTTP 200） -
/phpmyadmin/themes/your-theme/fonts/fontawesome-webfont.woff2→ 图标字体要能下载，否则菜单图标变方块
常见原因：
-
css/theme.css权限不是644，Web 用户（如www-data）不可读 - 启用了
$cfg['TempDir']，但该目录不可写，phpMyAdmin 无法动态合并 CSS，导致 fallback 到默认样式 - 主题里硬编码了绝对路径（比如
../fonts/...），而实际部署结构不同，路径解析失败
缓存清得不全，新主题根本没进浏览器
Ctrl+R 只刷新 HTML，theme.css、codemirror.css、字体这些静态资源早被浏览器、Nginx、PHP OPcache 多层缓存锁死。
必须按顺序清三处：
- 浏览器：用
Ctrl+Shift+R（Win/Linux）或Cmd+Shift+R（macOS），禁用 Dark Reader 等插件，用无痕窗口验证最准 - PHP 层：改过
config.inc.php或主题配置后，OPcache 可能缓存了它，执行sudo systemctl restart php*-fpm - Web 服务器：Nginx 的
expires 1y或 Apache 的mod_expires会让 CSS 缓存一年，临时注释掉再sudo nginx -s reload
真正卡住人的，往往不是缓存没清，而是清完发现 theme.json 里一个字段拼错了，或者目录名多了一个空格——它不报错，只安静消失。
