phpMyAdmin 主题安装后毫无反应，图标和 CSS 样式全部丢失，页面直接退化为纯文字界面，甚至出现“theme not found”的错误提示——这种情况通常并非主题本身损坏，而是 phpMyAdmin 根本没有扫描到您放入的主题文件夹。问题的根源大多集中在三个环节：目录结构、配置文件、Web 服务器权限。下面逐一排查。
确认 themes/ 目录结构是否符合 phpMyAdmin 的识别规则
phpMyAdmin 并不会“看到 themes/ 下有任何文件夹就自动加载”，它只识别特定命名和结构的主题。解压后的主题包如果直接扔进 themes/ 而未重命名或未清理多余层级，就会被系统跳过。
- 进入
themes/目录，执行ls -F，检查是否存在一个不含空格、不含点号、全小写、且不以.开头的子目录（例如pmahomme/），而不是phpmyadmin-themes-pmahomme-v5.2.0/或themes/pmahomme/这种嵌套结构 - 常见错误：下载的是带版本号的 zip 压缩包，解压后得到
phpmyadmin-themes-5.2.0/pmahomme/—— 必须将pmahomme/整个目录剪切出来，放到themes/根目录下，不能保留外层包装文件夹 - 主题目录内必须包含
theme.json（v5.0+ 版本）或info.inc.php（旧版本），缺失任一文件，phpMyAdmin 就会静默忽略该主题，不报任何错误
检查 $cfg['ThemePath'] 是否指向正确路径且未被覆盖
即便 themes/ 目录结构正确，$cfg['ThemePath'] 配置错误也会导致 phpMyAdmin 去错误位置查找主题，甚至直接禁用主题扫描功能。
- 打开
config.inc.php，搜索$cfg['ThemePath']—— 它必须是相对于 phpMyAdmin 入口文件index.php的相对路径，典型值为'./themes'（注意开头的./）；写成'themes'或'/var/www/html/phpmyadmin/themes'都会导致识别失败 - 再搜索
$cfg['ThemeDefault']，确保其值（例如'pmahomme'）与您放入themes/的目录名完全一致，包括大小写和拼写（pmahome≠pmahomme） - 某些 Docker 或宝塔插件环境会通过环境变量或外部配置覆盖
$cfg['ThemePath']，可临时在config.inc.php底部添加一行die(var_dump($cfg['ThemePath']));来确认实际生效的值
验证 Web 服务器是否允许访问 themes/ 下的静态资源
主题目录存在、路径配置正确，但浏览器直接请求 /phpmyadmin/themes/pmahomme/theme.json 返回 403 或 404，说明 Web 层拦截了访问——这是最容易被忽视的环节。
- Nginx 用户：检查 server 块中是否有
location /themes/ { deny all; }或类似限制代码；如有，删除或明确放开：location /themes/ { alias /path/to/phpmyadmin/themes/; } - Apache 用户：检查
themes/目录下是否意外存在.htaccess文件（尤其从其他项目复制过来时），内容含Deny from all；可临时重命名为.htaccess.bak进行测试 - SELinux 启用的系统（如 CentOS/RHEL）：即使
ls -l显示权限为 644，也可能因安全上下文被拒绝；运行ls -Z themes/pmahomme/，确认类型为httpd_sys_content_t；否则执行chcon -R -t httpd_sys_content_t themes/修正
真正卡住的地方往往不是主题本身，而是 phpMyAdmin 在扫描主题前就失败了：Web 服务器拒绝访问目录、$cfg['ThemePath'] 被多层配置覆盖、或解压后残留的隐藏目录结构导致扫描器直接跳过。动手前先用浏览器直接访问 /phpmyadmin/themes/ 看能否列出子目录，这比反复修改配置更节省时间。
