主题发布验收清单

本清单用于验证准备发布的主题 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@v5
    permissions:
      contents: write
    with:
      app-id: app-KgWqR # 替换为应用市场的应用 ID
    secrets:
      halo-pat: ${{ secrets.HALO_PAT }} # 应用市场的个人访问令牌

使用前确认：

pnpm build 的产物输出在 dist/ 目录，且 ZIP 内容符合构建与打包的约定；工作流会把 dist/ 下的全部文件上传到 Release。
如果 package.json 已声明 pnpm 的 packageManager，在 with 中设置 pnpm-version: ""，使用项目声明的版本。
版本号以 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 中包含不应分发的敏感文件。

构建并确认制品​

验证安装和升级​

覆盖页面和内容状态​

验证集成和浏览器表现​

配置持续发布（可选）​

记录发布证据​