主题结构、校验与打包发布

主题就是 themes/<id> 下的一个目录，不依赖 Go 代码。为了保证站点不会因为缺模板或错误标签而白屏，导入与启用前会执行完整校验。

最小目录结构

corporate/
  theme.json
  index.html
  list.html
  detail.html
  page.html
  search.html
  403.html
  404.html
  inc/
    head.html
    header.html
    footer.html
  assets/
    css/site.css
    js/site.js

theme.json

{
  "id": "corporate",
  "name": "企业官网",
  "version": "1.0.0",
  "engine": ">=1.0.0",
  "templates": ["index.html", "list.html", "detail.html",
    "page.html", "search.html", "403.html", "404.html"]
}

id 必须与目录名一致，字段不允许未知项。目录内所有 .html 文件都会参与校验，包括没有写进 templates 的可选模板和公共片段。

校验与打包

cms theme validate --source /path/to/themes/corporate

cms theme pack \
  --source /path/to/themes/corporate \
  --output /path/to/dist/corporate-1.0.0.zip

validate 会检查标签、属性、include 关系、资源类型和包限制；pack 会生成可重复构建的 ZIP，并用正式导入器再校验一次。

后台导入与启用

1. 进入“系统管理 → 主题管理”。
2. 导入 ZIP，校验成功后主题出现在本地列表，但不会自动启用。
3. 确认前台效果后点击“启用”，系统会再次执行完整校验并保存 site.theme。

升级与回滚

主题文件建议纳入版本管理。升级前备份 themes/ 与数据库站点设置；线上直接改过模板时，在线升级会检测到本地修改并拒绝静默覆盖。回滚时先恢复主题目录，再切换 site.theme。

缓存

主题文件变化会按文件指纹自动失效页面缓存，但浏览器与 CDN 仍可能缓存 CSS/JS。发布新版本时建议给静态资源加版本查询参数，或在 Nginx 层设置合理的缓存策略。