主题发布验收清单

本清单用于验证准备发布的主题 ZIP，而不只是开发目录。先按构建与打包生成并检查制品，再在 theme.yaml 的 spec.requires 所声明的 Halo 版本范围内完成安装和页面验收。

构建并确认制品

使用仓库已经提供的脚本；没有对应脚本时跳过，不要临时发明另一套发布流程：

pnpm install --frozen-lockfile
pnpm check # package.json 提供该脚本时执行
pnpm build
unzip -l dist/theme-name-version.zip
git status --short

确认以下结果：

构建和检查命令成功，生成模板来自本次源码。
ZIP 名称、theme.yaml 的 spec.version 和准备发布的版本一致。
ZIP 根目录直接包含 theme.yaml，并包含完整的 templates、配置、国际化资源及需要的 ui-plugin/dist。
ZIP 不包含源码、开发配置、凭据、私钥或其他无关文件。
构建后只有预期的产物变化，没有手工修改生成的 templates。

验证安装和升级

至少准备一个干净的 Halo 实例和一个安装了上一正式版主题的实例：

上传 ZIP，完成安装、启用和首次访问。
重载主题配置，确认 theme.yaml、settings.yaml 和默认值生效。
从上一正式版升级，确认已有设置仍可读取，新设置有安全的默认值。
切换到其他主题再切回，确认主题无需手工修复即可恢复工作。
完成停用和卸载流程，确认不影响站点内容和其他主题。
在声明范围内的最低 Halo 版本和计划支持的当前版本上重复关键路径；只在新版可用的片段应使用 #halo.matchVersion 保护。

不要根据“模板能编译”推断兼容范围。spec.requires 应只覆盖实际验证过且功能可接受的 Halo 版本。

覆盖页面和内容状态

范围	至少验证
核心页面	首页、文章、单页面、文章归档、分类列表与分类归档、标签列表与标签归档、作者归档、错误页
自定义模板	`theme.yaml` 中声明的每一个文章、单页面和分类模板
内容边界	空列表、单条内容、多页内容、长标题、无摘要、无封面、宽表格、代码块和嵌入媒体
分页与链接	上一页、下一页、详情链接、面包屑、菜单、站内搜索入口和不存在的地址
主题设置	默认配置、每个开关、空值、自定义颜色或图片，以及重载配置后的结果
国际化	主题声明的每种语言、日期和数字格式，以及窄屏下的长文本

页面不能出现服务端错误、失效入口、资源 404、明显布局溢出或阻断主要操作的 JavaScript 错误。

同时确认模板没有使用 Thymeleaf 3.1 已移除的请求对象或未经确认的表达式方法；具体检查参考 Thymeleaf 模板语法。站点 Logo、SEO 和代码注入等系统能力不应在主题设置中重复提供。

验证集成和浏览器表现

按与插件集成分别测试插件未安装、已停用、版本不满足和正常启用的状态。
如果提供 templates/layout.html，用实际插件前台页面验证页面布局契约，不能只测试主题自己的页面。
检查桌面和窄屏布局、键盘操作、可见焦点、图片替代文本、颜色对比度和水平滚动。
检查浏览器 Console 和 Network，确认没有未处理异常、混合内容、重复请求或意外外部资源。
按主题 SEO检查最终 <head>，尤其是标题、描述、noindex、canonical 和社交分享信息。
可访问性：页面有唯一的 h1 和合理的标题层级， landmarks（header/nav/main/footer）完整，表单控件有关联标签，仅依赖键盘可以完成主要操作。可借助浏览器开发者工具的 Lighthouse 或 axe 面板复查。
关闭模板缓存进行开发验证后，再用接近生产的缓存配置完成一次冒烟测试。

配置持续发布（可选）

如果主题托管在 GitHub，可以使用 halo-sigs/reusable-workflows 提供的 theme-cd.yaml 可复用工作流，在发布 GitHub Release 时自动执行 pnpm build、上传 ZIP 到 Release，并可选地同步到 Halo 应用市场：

.github/workflows/cd.yaml

name: CD

on:
  release:
    types:
      - published

jobs:
  cd:
    uses: halo-sigs/reusable-workflows/.github/workflows/theme-cd.yaml@v4
    permissions:
      contents: write
    with:
      app-id: app-KgWqR # 替换为应用市场的应用 ID
    secrets:
      halo-pat: ${{ secrets.HALO_PAT }} # 应用市场的个人访问令牌

使用前确认：

pnpm build 的产物输出在 dist/ 目录，且 ZIP 内容符合构建与打包的约定；工作流会把 dist/ 下的全部文件上传到 Release。
版本号以 Git 标签和 theme.yaml 的 spec.version 为准，发布前确认两者一致。
不需要同步应用市场时，设置 skip-appstore-release: true 并省略 app-id 与 halo-pat。

记录发布证据

发布记录至少保留以下信息，方便人工复核或 AI Agent 在后续版本中比较：

Commit:
Theme version:
Halo versions tested:
Clean install: pass/fail
Upgrade from: version, pass/fail
Commands run:
Routes checked:
Optional plugins checked:
Known limitations:
Artifact path and SHA-256:

macOS 可以使用 shasum -a 256 dist/theme-name-version.zip 生成摘要。发现以下任一问题时应停止发布：构建或打包失败、无法安装或启用、主要页面返回服务端错误、缺少可选插件时主题不可用、制品版本不一致，或 ZIP 中包含不应分发的敏感文件。

主题发布验收清单#

#构建并确认制品

#验证安装和升级

#覆盖页面和内容状态

#验证集成和浏览器表现

#配置持续发布（可选）