主题测试与发布
校对日期:2026-11-16。适用于社区版及全部商业版。
本文面向主题开发者和发布方,说明主题交付前的检查与测试、打包、安装、预览、激活和更新,以及发布验收清单。 主题的组成和开发环境见主题开发。
一、检查与测试
1.1 FreeMarker 语法检查
仓库提供模板语法解析与转义检查,会遍历 themes/ 下除 node_modules 外的全部 .html:
./mvnw -pl ujcms-cms -am \
-Dtest=ThemeTemplateParseTest \
-Dsurefire.failIfNoSpecifiedTests=false test该检查能发现 FreeMarker 解析错误和未放入本文件 [#escape] 块的插值,但不能替代运行时 include、指令参数和真实数据验证。
1.2 Schema 与文档检查
主题的 JSON 文件应在编辑器中关联 $schema。系统也会在加载或安装时用同一份 Schema 校验。 修改仓库内置 Schema 或参考组件后运行:
node scripts/generate-composition-docs.mjs --check
node scripts/check-doc-links.mjs只制作第三方主题时,不需要修改生成的 theme-authoring.md;应修改 JSON 源文件并让生成脚本 维护该参考文档。
1.3 页面和视觉验收
默认主题的验收套件位于 ujcms-theme-e2e。制作新主题时可以复制并改造其中的 Playwright 用例和视觉基线;不要直接把默认主题截图断言当作新主题的通过标准。
至少测试:
- 首页、所有栏目/文章/专题变体及主题实际提供的系统页面。
- 匿名、已登录、无权限、空数据和数据量较大的状态。
- 360~390 px 手机、平板和桌面宽度。
- 长标题、缺图、失效引用、无演示数据和分页末页。
- 导航、表单、弹窗、轮播、下载和 AJAX 追加内容。
- 浏览器控制台无 JavaScript 异常,网络面板无主题资源 404。
- 页面源代码中没有泄漏
${...}、FreeMarker 堆栈或敏感对象字段。 - SEO、无障碍、性能和 CSP 行为。
- 桌面主题与手机主题分别激活时的资源和模板解析。
二、打包主题
2.1 打包前清理
发布前先执行生产构建,然后确认不包含:
node_modules/。.git/、编辑器目录、临时文件、日志和测试报告。.DS_Store、__MACOSX/等操作系统元数据。- 未使用的大型设计源文件。
- 密码、密钥、Token、内部域名或数据库导出。
_src/、package.json 和锁文件不是运行所必需。是否随包提供取决于发行策略;无论是否提供, assets/ 中都必须已有可直接运行的产物。
主题根目录的许可证与说明文件必须随包:LICENSE 或 LICENSE.md(协议文本,与清单的 license 字段一致)、 THIRD-PARTY-NOTICES.md(主题包含的第三方组件及其许可证,没有第三方组件时可省略)、SEED-MEDIA.md(随包图片、视频、 文档的来源,没有媒体文件时可省略)。scripts/ 打包时保留这三类文件,纯数据包也不例外。
2.2 ZIP 根目录
必须压缩主题目录中的内容,不能把主题文件夹本身作为 ZIP 中唯一的外层目录。
正确:
acme-1.0.0.zip
├── theme.manifest.json
├── templates/index.html
├── layout/theme.html
└── assets/css/style.css错误:
acme-1.0.0.zip
└── acme/
├── theme.manifest.json
└── templates/index.html在主题目录内可执行:
cd ujcms-starter/src/main/webapp/themes/1/acme
npm run build
zip -r ../../../../../../../acme-1.0.0.zip . \
-x 'node_modules/*' '.git/*' '.DS_Store' '__MACOSX/*'也可以把 ZIP 输出到指定的安装包输出目录。打包后检查:
unzip -l acme-1.0.0.zip
shasum -a 256 acme-1.0.0.zipLinux 可使用 sha256sum。保存并通过可信渠道公布 SHA-256 摘要,安装完成后将其与控制台显示的摘要进行比对。
2.3 安装器主要约束
- 默认上传及总解压大小上限为 50 MB,可由系统配置调整。
- 最多 10,000 个 ZIP 条目,单个路径最长 240 个字符。
- 至少一个
.html文件必须直接位于 ZIP 根的templates/下。 theme.如存在,必须是合法 JSON,且大小不超过 64 KiB。manifest. json kind只能是theme或data-only。pages/、shapes/、seed/、i18n/只能存放 JSON 文件,seed/除外。content/ assets/ - 拒绝绝对路径、反斜杠路径、
./..、Windows 保留设备名和 Zip Slip 路径。 data-only包不能携带渲染模板,也不能激活为站点主题。
具体校验规则见 ThemeInstallValidator.java。
三、安装、预览、激活与更新
3.1 首次安装
在控制台“设计 → 主题”中选择上传主题包:
- 选择目标站点和 ZIP。
- 确认主题标识。
- 选择是否安装后激活,以及激活到桌面、手机或两者。
- 选择演示数据导入范围:不导入、仅导入页面布局或导入全部演示数据。
- 检查安装警告、种子失败明细和 ZIP SHA-256。
上传的 ZIP 会先进入主题包库,再安装为站点自己的主题实例。主题也可从主题包库或应用市场安装。
3.2 激活前预览
使用主题画廊的“预览”在不替换当前公开主题的情况下浏览候选主题。至少检查首页、一个栏目页、 一个文章页和主题声明的主要变体。确认预览效果后,先查看激活操作的影响范围,再切换主题。 逐个模板文件的预览见模板编写的“预览单个模板”一节。
3.3 更新主题
发布更新时:
- 更新
version版本号,并维护面向管理员的变更说明。 - 保持
themeName、页面name、区域名、Shapename和种子originId稳定。 - Shape 字段发生不兼容变化时编写
migrations,不要只改版本号。 - 新增字段优先给默认值,确保旧站点没有保存值时仍可渲染。
- 先在复制站点或沙箱站点验证更新、种子差异和管理员已修改数据的保留行为。
- 不要依靠主题更新覆盖管理员内容;种子数据默认不会覆盖管理员已修改的内容。
更换主题包时,系统仅导入新增的种子数据,跳过已有记录。之后可在控制台“设计 → 主题 → 演示数据管理”(主题详情的“演示数据”选项卡) 中按需选择以下三种处理方式之一:
- 导入演示数据(默认):跳过已有的主题来源记录,仅补充新增的种子数据。
- 更新未修改项:通过哈希值判断记录是否被修改,仅更新管理员未修改的主题来源记录,跳过已修改的记录。
- 还原演示数据:使用种子数据覆盖所有主题来源记录,操作前会显示红色警告并要求确认。管理员自行创建的记录会保留; 本主题的区域布局会整体恢复为默认布局。重建前的草稿和已发布布局会先存入区域发布历史,可在构建器中按区域分别恢复。
3.4 安全边界
安装 FreeMarker 主题等同于在服务器上运行受信模板代码。只有与修改服务器代码同等可信的 管理员才应拥有 theme:install 和模板文件编辑权限。主题作者必须:
- 不遍历或输出与页面无关的对象字段。
- 不在公开页面输出会员手机号、邮箱等个人信息。
- 不绕过 HTML 转义、CSRF 或 CSP。
- 不把外部上传内容直接作为原始 HTML 输出。
- 不加载来源不可控的远程脚本。
- 明确声明第三方资源的许可证并锁定版本。
运维侧的完整说明见主题安全与部署约束。
四、发布验收清单
主题结构
- [ ]
theme.的名称、标识、版本、最低版本和截图正确。manifest. json - [ ] ZIP 根目录没有多包一层主题文件夹。
- [ ] 至少存在一个
templates/。*. html - [ ] 所有运行时所需的 CSS、JS、图片、字体和第三方依赖文件均已打包。
- [ ]
node_modules、密钥、临时文件和系统元数据未进入 ZIP。 - [ ] 清单的
license字段与根目录的LICENSE/LICENSE.md一致;第三方组件列在THIRD-PARTY-NOTICES.md,随包媒体的来源列在SEED-MEDIA.md。
模板与数据
- [ ] 每个包含插值的
.html文件都有自己的[#escape]块。 - [ ] 只有明确已净化的富文本字段使用
[#noescape]。 - [ ] 所有使用到的模板变量和指令参数均有文档或参考主题依据。
- [ ] 空列表、空图片、可选字段和失效引用均有相应的提示或替代内容。
- [ ] URL、接口和资源路径没有写死域名、站点 ID 或部署上下文。
- [ ] 内联脚本携带
${csp_nonce!''},写请求正确处理 CSRF。
清单、组件与种子
- [ ] 页面清单模板绑定唯一且准确。
- [ ] 每个区域使用的 Shape 都由本主题声明,并有同名面板模板。
- [ ] JSON 文件通过运行时 Schema 校验。
- [ ] 区域种子的页面、区域、Shape 和列数均能解析。
- [ ] 内容种子使用稳定 ID,重复导入不破坏管理员修改。
- [ ] 不导入种子时主题仍可正常显示空状态。
体验与发布
- [ ] 主要页面完成桌面、平板、手机验收。
- [ ] 匿名、登录和权限受限状态均已测试。
- [ ] 页面无控制台错误、资源 404 和 FreeMarker 表达式泄漏。
- [ ] 标题、描述、Canonical、结构化数据和无障碍基础正确。
- [ ] 主题 ZIP 经真实上传、预览、激活、更新和卸载流程验证。
- [ ] 发布方保存并公示 ZIP SHA-256。
五、常见问题
上传后提示缺少模板
确认 ZIP 根目录直接包含 templates/ 等文件。最常见原因是压缩了外层主题目录,形成 acme/。