换主题后CSS不生效的根本原因是浏览器、PHP OPcache、Web服务器三层缓存未同步清除：Ctrl+R仅清HTML缓存，而theme.css等资源受强缓存保护；OPcache未重载config.inc.php导致$cfg['ThemeDefault']未更新；Nginx/Apache的expires指令使静态资源直接返回304。必须严格按浏览器→PHP→Web服务器顺序清除，并确保theme.json字段（name、compat_version）、目录权限（644）、路径可读写全部合规，否则主题静默回退至默认blue且无报错提示。
换主题后CSS不生效，不是主题没装对，而是缓存链路里至少有一环没断开——浏览器、PHP OPcache、Web服务器三者必须同步清除，缺一不可。
为什么 Ctrl+R 刷新没用
因为 Ctrl+R 只清 HTML 文档缓存，而主题的 theme.css、codemirror.css、字体文件（如 fontawesome-webfont.woff2）被多层独立缓存拦截：
- 浏览器对 CSS/字体资源启用强缓存（
Cache-Control: public, immutable），按 F5 不触发重载 - PHP OPcache 缓存了
config.inc.php，若你改过$cfg['ThemeDefault']，新值根本没加载 - Nginx/Apache 配置了
expires 1y，静态资源返回 304，连服务器都不走
验证方式：直接在浏览器地址栏访问 /phpmyadmin/themes/your-theme/css/theme.css，如果返回 404 或 304，说明某层缓存或路径已卡死。
必须依次清除的三层缓存
顺序不能颠倒，否则下一层会立刻把上一层刚清掉的内容再“固化”回去：
立即学习“PHP免费学习笔记（深入）”；
-
浏览器端：用
Ctrl+Shift+R（Windows/Linux）或Cmd+Shift+R（macOS），禁用所有插件（尤其 Dark Reader 会劫持 CodeMirror 样式）；最可靠的是开无痕窗口测试 -
PHP 层：执行
sudo systemctl restart php*-fpm（如php8.2-fpm），确保 OPcache 重载config.inc.php和主题配置 -
Web 服务器层：Nginx 中临时注释掉
location /themes/ { ... }或expires指令，然后sudo nginx -s reload；Apache 用户检查mod_expires是否启用，并临时关闭
theme.json 和目录结构必须严格匹配
即使缓存全清，主题仍静默回退到默认 blue 主题——它不会报错，只会跳过加载。关键硬性条件：
-
themes/your-theme/theme.json中的"name"字段必须与目录名**完全一致**（大小写、连字符、无空格），例如目录是dracula，"name"就只能是"dracula" -
"compat_version"必须精确匹配 phpMyAdmin 主版本号（如"5.2"），填"5"或"5.2.1"都会导致主题被忽略 -
themes/your-theme/css/theme.css权限需为644，且 Web 进程用户（如www-data）可读；若启用了$cfg['TempDir']，该目录必须可写，否则 CSS 合并失败
快速验证是否真正生效
别靠肉眼等页面渲染完再猜，直接查网络请求和资源响应：
- 浏览器地址栏输入
/phpmyadmin/themes/your-theme/css/theme.css，确认返回 HTTP 200 和真实 CSS 内容 - 访问
/phpmyadmin/themes/your-theme/fonts/fontawesome-webfont.woff2，确保字体可下载（避免图标变方块） - 打开开发者工具 → Network → 刷一次页面 → 筛选
css和font类型，所有主题相关资源状态码必须是 200，不能有 304 或 404
真正卡住人的往往不是“怎么清缓存”，而是清完发现 theme.json 里一个字段写错，或者目录权限漏掉执行位（x），导致整个主题被跳过——它安静得毫无提示。
