phpMyAdmin主题必须严格遵循目录结构和theme.json规范才能生效，否则回退默认或报错；需置于themes/子目录，含theme.json、css/theme.css及可选img/，且compat_version须精确匹配phpMyAdmin主版本号。
phpmyadmin 主题不能靠“复制粘贴 css”就生效，必须严格遵循其主题目录结构和 theme.json 元数据定义，否则界面会回退到默认主题或报错 theme not found。
主题目录结构必须满足 phpMyAdmin 5.0+ 的强制约定
从 5.0 开始，phpMyAdmin 不再接受任意路径的 CSS 注入，所有主题必须放在 themes/ 子目录下，且包含特定文件：
-
themes/your-theme-name/theme.json：必存，描述主题名称、作者、兼容版本等，缺则被忽略 -
themes/your-theme-name/css/theme.css：主样式表，路径固定，不可改名或挪动 -
themes/your-theme-name/img/：可选，但所有图片引用必须相对此路径，background: url(img/icon.png) - 不支持
scss或less源文件——必须提供编译后的theme.css
theme.json 里 version 和 compat_version 容易填错
这两个字段不是随意写的版本号，它们直接决定 phpMyAdmin 是否加载该主题：
-
version是你主题自身的版本（如"1.0.0"），纯标识作用 -
compat_version必须匹配 phpMyAdmin 主版本号，例如你的 phpMyAdmin 是 5.2.1，则填"5.2"；填"5"或"5.2.1"都会失败 - 常见错误：把
compat_version写成 PHP 版本（如"8.1"）或 MySQL 版本，导致主题列表里完全不显示
示例 theme.json 片段：
{
"name": "Nord Light",
"author": "you",
"version": "1.0.0",
"compat_version": "5.2"
}
CSS 选择器必须适配 phpMyAdmin 的 DOM 结构变化
新版 phpMyAdmin 大量使用 BEM 风格类名（如 table--responsive、navigation__item），旧主题直接复用 Bootstrap 或 AdminLTE 的规则基本无效：
立即学习“PHP免费学习笔记（深入）”；
- 不要写
.navbar-default—— 这个类在 5.0+ 已移除 - 关键区域优先用属性选择器定位，比如
[data-submenu]替代.submenu - 颜色变量不可用 CSS 自定义属性（
--pma-bg等）覆盖，因为 phpMyAdmin 不注入这些变量，得直接重写元素样式 - 字体大小建议用
rem，避免被 phpMyAdmin 的html { font-size: 62.5%; }意外缩放
发布前必须验证 theme.json 和路径权限
即使 CSS 看起来正常，部署后仍可能黑屏或白屏，问题常出在：
-
themes/your-theme-name/目录权限不是 webserver 可读（如 Apache 用户无法stat到theme.json） -
theme.json有 UTF-8 BOM 或语法错误（多一个逗号、少一个引号），phpMyAdmin 会静默跳过整个主题 - 服务器启用了
opcache.restrict_api，导致json_decode(file_get_contents(...))返回null - 没清空浏览器缓存 + phpMyAdmin 的主题缓存（
$cfg['TempDir']下的theme_*.css文件）
调试时可临时在 libraries/classes/Theme.php 中加 error_log("Loaded: $name") 确认是否被识别。
最常被忽略的是 compat_version 和 theme.css 的硬编码路径——写错一个字符，主题就等于不存在。
