答案是皮肤文件结构必须严格匹配phpmyadmin版本规范：themes/下须含theme.json（含name、version、author及mtime）、theme.css、preview.png和img/等完整文件集，缺一不可；theme.json的name必须与目录名完全一致，version建议对齐主版本，$cfg['themedefault']须严格匹配该name，且需手动清除cache/themedata.php缓存。
皮肤文件结构必须严格匹配 phpMyAdmin 版本的 themes/ 目录规范
phpMyAdmin 不支持任意目录结构的“主题包”，所有自定义皮肤必须放在 themes/ 子目录下，且需包含完整的基础文件集。缺失 theme.css、theme.json 或 preview.png 会导致后台主题列表不显示该皮肤，甚至引发 500 错误。
实操建议：
-
theme.json必须有"name"、"version"、"author"字段，且"version"建议与当前 phpMyAdmin 主版本对齐（如 5.2.x 环境下设为"5.2.0"），否则升级后可能被自动禁用 - CSS 文件不能仅覆盖 logo —— 必须重置
.logo、.navbar、.container、.tab等核心类的默认样式，否则企业色在深色模式或响应式折叠时会失效 - 所有图片资源（logo、favicon、preview）必须放在
themes/your-brand/img/下，并在 CSS 中用相对路径引用，如background: url(./img/logo.svg)；绝对路径或 Web 路径（/themes/...）会被安全策略拦截
修改 logo 和 favicon 需绕过 phpMyAdmin 的硬编码缓存逻辑
直接替换 themes/original/img/logo.svg 并不会生效——phpMyAdmin 在生成 HTML 时会拼接带时间戳的 URL，例如 logo.svg?1678892340，而该时间戳来自文件系统 mtime，但仅对内置主题生效。自定义皮肤若未在 theme.json 中声明 "mtime"，则始终使用默认时间戳，导致浏览器缓存旧 logo。
实操建议：
- 在
theme.json中显式添加"mtime": 1712345678（用date +%s生成真实时间戳），确保每次部署新 logo 后更新该值 - favicon 必须同时提供
favicon.ico（16×16/32×32）和favicon.svg，并确保theme.css中无link[rel="icon"]的重复注入逻辑（phpMyAdmin 会自动注入，额外写会导致双图标） - 若企业要求深色 logo 适配夜间模式，需在 CSS 中用
@media (prefers-color-scheme: dark)单独控制.logo img的filter: brightness(0) invert(1)，不能依赖 JS 切换
避免在 theme.css 中使用 @import 或外部字体链接
phpMyAdmin 默认禁用远程资源加载，且其 CSP 策略（由 $cfg['CSPAllowExternalResources'] = false 控制）会拦截所有非同源 CSS @import 和 url() 外链。强行引入 Google Fonts 或 CDN 字体将导致样式断裂，控制台报 Refused to load the stylesheet 错误。
实操建议：
- 字体文件（如
Inter.woff2）必须下载后放入themes/your-brand/fonts/，并在 CSS 中用@font-face本地声明，src 使用url(./fonts/Inter.woff2) - 禁止在
theme.css里写@import url("https://fonts.googleapis.com/css2?...")，即使临时开启CSPAllowExternalResources，也会因 phpMyAdmin 的 inline-style 注入机制导致字体规则被剥离 - 如需中文字体，优先选用 Noto Sans SC 等可商用开源字体，并只打包常用字重（400/500/700），避免单个 CSS 超过 200KB 引发加载阻塞
权限与部署后必须验证 $cfg['ThemePath'] 和 $cfg['ThemeDefault'] 配置
即使皮肤文件就位，若 config.inc.php 中未正确设置 $cfg['ThemePath'] 指向自定义目录，phpMyAdmin 仍会回退到 themes/original；更隐蔽的问题是：当 $cfg['ThemeDefault'] 值与 theme.json 中的 "name" 不完全一致（含空格、大小写、连字符），登录后界面会静默降级为 default 主题，且无任何错误提示。
实操建议：
-
$cfg['ThemePath']必须是相对于 phpMyAdmin 根目录的路径，例如'themes'（默认）或'/var/www/internal-themes'（需确保 Web 用户有读取权限） -
$cfg['ThemeDefault']应严格等于你皮肤文件夹名，例如皮肤放在themes/acme-enterprise，则值必须为'acme-enterprise'，不能写成'AcmeEnterprise'或'acme_enterprise' - 部署后访问
http://your-pma/setup/→ “Theme” 标签页，确认你的皮肤出现在下拉列表中且可选中；若不可见，检查 PHP 错误日志中是否出现file_get_contents(.../theme.json): failed to open stream
最易被忽略的是：phpMyAdmin 会在首次加载主题时生成缓存文件 cache/themedata.php，修改 theme.json 或 CSS 后必须手动删除该文件，否则变更永不生效。
php免费学习视频：立即使用
踏上前端学习之旅，开启通往精通之路！从前端基础到项目实战，循序渐进，一步一个脚印，迈向巅峰！
