phpMyAdmin 5.2+主题需重构目录结构并迁移至Twig：旧主题须新建templates/和css/子目录，添加theme.json，重命名.mustache为.twig，更新变量语法与控制结构，适配新HTML类名，删除已废弃的Theme.class.php。
phpMyAdmin 5.2+ 主题目录结构变了，旧主题直接复制会报错
新版本把 themes 目录下的主题从「平铺」改成了「按命名空间分层」，比如旧版路径是 themes/original/，新版必须是 themes/original/templates/ + themes/original/css/ + 显式声明的 theme.json。不补全结构，登录页就卡在「error: theme not found」或白屏。
实操建议：
- 进旧主题文件夹，新建
templates/和css/子目录，把原./下的*.mustache全挪进templates/，*.css全挪进css/ - 在主题根目录（如
themes/original/）下新增theme.json，至少包含：{ "name": "original", "version": "4.9.0", "parent": "pmahomme" }（parent必须填，推荐用官方默认主题pmahomme） - 检查
config.inc.php中是否还留着过时的$cfg['ThemePath']或$cfg['ThemeDefault']—— 新版只认$cfg['Server']['pmahomme']级配置，这些老配置删掉更安全
模板语法升级：Mustache 变成 Twig，template.twig 里不能写 {{PMA_VERSION}}
phpMyAdmin 5.0 起全面迁移到 Twig，所有 .mustache 文件必须重命名为 .twig，且变量访问方式从双大括号裸写变成带命名空间前缀，比如 {{ PMA_VERSION }} 会报 Variable "PMA_VERSION" does not exist。
实操建议：
- 把
templates/*.mustache全部重命名为templates/*.twig - 全局替换：把
{{换成{{ cfg.（对应配置项）、{{ lang.（对应语言字符串）、{{ server.（对应服务器信息）—— 具体前缀得看上下文，最稳妥是查新版源码里同位置模板怎么写的 - 别硬套旧逻辑：像
{{#is_superuser}}...{{/is_superuser}}这类 Mustache 块必须改成 Twig 的{% if is_superuser %}...{% endif %}，否则直接解析失败
CSS 选择器失效：新版 HTML 结构重写，.container 可能已不存在
5.x 版本重构了几乎所有页面的 DOM 结构，比如导航栏从 <div class="container"> 换成了 <nav id="server-breadcrumb">，旧主题 CSS 里写的 .container > .navbar 完全不生效，导致样式大面积丢失。
立即学习“PHP免费学习笔记（深入）”；
实操建议：
- 打开浏览器开发者工具，右键页面任意元素 → 「检查」，对比新版 HTML 和你旧主题 CSS 里写的类名是否还存在
- 优先复用官方主题的 CSS 类名：比如新版侧边栏是
#navigation，顶部工具栏是#topmenu，按钮统一加了.btn类，别自己造新类 - 避免用深度嵌套选择器（如
div div div .button），新版 DOM 层级变浅，这类规则极易断链；改用语义化单类名 +:is()或:where()做兼容
PHP 后端钩子移除：Theme.class.php 的 getHtmlFor... 方法全无效
旧主题靠 Theme.class.php 里的方法（如 getHtmlForNavigation()）注入 HTML，但新版已废弃该机制，所有前端渲染由 Twig 模板和 Vue 组件控制，PHP 层不再提供可覆盖的钩子。
实操建议：
- 直接删掉
Theme.class.php—— 它不会被加载，留着反而可能触发 PHP 警告 - 想改导航栏内容？去改
templates/navigation.twig，而不是试图 hook 一个不存在的方法 - 需要动态数据？用 Twig 的
{{ include('partial.twig') }}拆分逻辑，或通过$GLOBALS['plugin_scripts']注入 JS 在前端处理，PHP 层不参与渲染逻辑
真正麻烦的是那些依赖 DOM 操作的 JS 插件——它们绑定的元素 ID 或 class 名大概率已变，得对照新版 HTML 逐个调。别指望“兼容模式”，phpMyAdmin 没留后门。
