v1.11.0:模板主题管理,前台模板按站点切换
2026 年 11 月 11 日,卫民CMS 演示站交付 v1.11.0:模板主题管理。这一版新增 wm_theme 表与 wm_site.theme_id 列,后台可以列出主题包、查看 theme.json 与模板文件清单、启用或停用主题,并按当前编辑站点切换前台模板。改动仍然全部集中在后台与模板层机制,前台视觉、主 CSS 与 Logo 均保持不变。
为什么把「模板适配」产品化
客户已有前端设计稿接入 CMS,过去是一次性的适配开发:每套设计对应一份代码副本,切换与复用都要人工改目录。把模板文件与元信息收拢成可整包拷贝的主题包、把绑定关系落到站点表,接入流程就从「改代码」变成「装主题包 + 后台绑定」。这一版不提供一键导入 HTML,也不做可视化拖拽建站,边界如实保留。
第一个坑:模板目录不能改全局配置
后台 app/admin/view/ 与前台共用 config/view.php。若直接改全局配置的 view_path,后台模板会一起被指向 themes/,整个后台立刻打不开。更不能把注入中间件挂到 app/index/middleware.php:前台请求走 /index.php?s=xxx.html,没有应用名前缀,多应用解析返回 false,应用级管道根本不执行 —— 这正是 v1.8 静态缓存中间件「装了等于没装」的同一个坑,表现为「页面正常、主题却没换」。
最终做法是把 ThemeViewPath 注册到全局 app/middleware.php,顺序为 StaticCacheMw → ThemeViewPath → SessionInit;中间件内部判定 /admin.php 请求直接跳过注入,只在前台请求里用 Config::set(['view_path' => ...], 'view') 改写模板目录,配置文件本身不动。命中静态缓存时前一个中间件已经短路返回,本中间件也不会多余执行。
第二个坑:静态缓存命中时不渲染模板
整页静态缓存命中后直接返回磁盘 HTML,控制器与模板引擎都不会跑。如果缓存键里只有站点 id,切换主题后前台会一直命中旧主题的 HTML,看起来就像「切换没生效」。因此 StaticCacheMw 与 StaticBuild 两处的键同时改为 <site_id>/<theme_code>/<pathinfo>,主题上下文由 ThemeContext 统一提供,避免三处各查一次库产生算法漂移。切换动作显式清空全部静态缓存,再重新预热。
静态页生成命令也一并改造:从「只用单一 Host 生成一套 URL」变为遍历所有启用站点、按各自域名作 Host 预热,并按各站点绑定主题的键前缀落盘。部署前用只读探针实测了两个站点的 Host 头确实解析到各自内容,才启用多站点预热。
第三个坑:种子必须把 theme_id=0 清零
与 v1.10 第二批 role_id=0 同类:只插入内置 default 主题、不把现存站点的 theme_id 指过去,启用主题中间件后所有站点都会回退 default —— 页面看起来完全正常,但后台绑定关系全丢、后续切换必然失效,且极难在验收里发现。种子脚本因此显式断言 theme_id=0 剩余行数必须为 0,否则退出码 1、中止上传源码。
部署顺序与验收
先做线上现读断言与时间戳备份,再执行 DDL、跑种子、复核 theme_id=0 为 0,接着上传两套主题包并逐文件 md5 比对,最后才上传源码;远端 php -l 全绿后清三处模板缓存,执行 static:clear 与 static:build(要求失败 0),再用真域名无查询串复验并做 PC / 375px 截图。
验收逐项覆盖:主题表结构与索引、默认主题 12 个模板逐字节一致、默认主题下前台视觉零变化、缓存键带主题、切主题后渲染新模板并命中缓存、切回 default 可完全还原、站点隔离、RBAC 越权拦截、演示账号只读、切换产生一条操作日志且不影响前台缓存、后台模板不受注入影响,以及按回滚 SQL 可还原。默认主题是现有模板的原样副本,切回默认即可验证视觉没有变化。
改动范围
新增 wm_theme 与 wm_site.theme_id;新增主题模型、后台控制器与列表 / 详情页、两个权限点与菜单入口、只读主题说明页;改造两处缓存键与静态页生成命令;新增两套主题包(默认主题与原模板逐字节一致,示例主题仅在布局上追加一处标记)。前台视觉、主 CSS、Logo 与版本号数据均不在本批改动内。