> For AI agents: the complete documentation index is available at https://docs.halo.run/llms.txt, the full documentation bundle is available at https://docs.halo.run/llms-full.txt.

# 测试与发布

以下检查面向 Halo 商城版 2.27。根据主题支持的商品与支付方式准备测试数据，在开发环境完成完整流程。

## 准备测试数据

至少准备有图和无图商品、多 SKU 商品、库存不足商品、外链商品、询价商品，以及主题声明支持的订阅商品。实体商品验证收货地址和发货信息，虚拟商品配置数字资源或卡密；使用测试数据验证订单内容。Halo 商城版 2.27 尚未实现配送方式选择与运费计算。

分别测试登录用户、未登录访客、开启游客结算后的游客。订阅商品还需要已有订阅和无订阅的登录用户。

## 页面与交互检查

| 场景   | 检查内容                           |
| ---- | ------------------------------ |
| 商品列表 | 空列表、关键词、分类、排序、分页；翻页保留筛选条件      |
| 商品详情 | 正文、无图占位、图库、永久链接、SKU 切换与数量限制    |
| 订阅商品 | 档位和周期、数量上下限、试用提示、已有订阅入口；游客需要登录 |
| 购物车  | 添加、修改、删除、空购物车、库存或价格发生变化        |
| 结算   | 新地址、地址簿、游客邮箱、备注、优惠码和优惠券拒绝原因    |
| 支付   | 可用方式、支付失败、超时、切换方式、刷新和返回页面      |
| 订单   | 待支付、已支付、取消、退款、优惠明细、快递和虚拟履约信息   |
| 游客订单 | 下单后访问、邮件访问、失效链接、邮箱找回、附件下载和卡密展示 |

结算上下文依赖会话，补测刷新、浏览器后退、重新发起结算、会话过期等情况。订单价格发生变化或商品失效时，应展示服务端错误并允许顾客恢复操作。

## 样式与兼容性

- 桌面与窄屏分别检查列表、图库、表单、支付二维码和订单长内容。
- 使用主题支持的浅色、暗色和语言配置检查按钮、输入框、状态提示。
- 从浏览器查看页面源代码，确认商品标题、介绍和正文已由 Thymeleaf 输出。
- 检查同一页没有重复注册 `shop-*` 组件，商城静态资源成功加载。
- 覆盖模板后仍保留 CSRF 字段，交易请求正确携带会话 Cookie。
- 测试主题声明支持的支付环境，包括需要支持时的微信内置浏览器和手机浏览器。

## 常见问题

| 现象                  | 排查方向                                                                                                        |
| ------------------- | ----------------------------------------------------------------------------------------------------------- |
| 所有商城页面返回 404        | 确认运行商城版、商城已启用，路径与目标版本匹配                                                                                     |
| 自定义模板未生效            | 检查激活主题、`templates/shop/` 路径及文件名；开发环境模板缓存设置见[主题开发准备](https://docs.halo.run/developer-guide/theme/prepare.md) |
| 出现 `shop-*` 标签但没有内容 | 检查 JavaScript 加载、组件注册及必需属性                                                                                  |
| 自定义元素重复注册           | 是否同时加载内置脚本和自编译的商城 UI                                                                                        |
| 商品图库不工作             | 源码开发时是否遗漏根入口中的 Swiper 和图片放大初始化                                                                              |
| 组件样式缺失或错乱           | 检查 CSS 引用、加载顺序和主题全局样式冲突                                                                                     |
| 结算页跳回购物车            | 结算上下文不存在、过期或与当前会话不匹配                                                                                        |
| 订单 JSON 请求返回 HTML   | 设置 `Accept: application/json`，并检查是否跳转到登录页                                                                   |
| 游客订单 JSON 返回 404    | 检查访问链接及 Cookie，提供邮箱找回入口                                                                                     |
| 写请求返回 403           | 检查登录要求、会话和 CSRF 令牌，必要时刷新页面                                                                                  |
| 分类列表不显示             | 分类 Finder 使用 `content`，商品 Finder 使用 `items`                                                                 |

## 打包与升级

按[主题打包规范](https://docs.halo.run/developer-guide/theme/packaging.md)和[发布检查清单](https://docs.halo.run/developer-guide/theme/release-checklist.md)生成安装包。复用内置模板时，只打包主题实际覆盖的文件；源码开发时，先构建 UI 与主题资源，再确认安装包包含模板引用的最终文件。

在主题说明中标明“需要 Halo 商城版”与已验证的最低版本。不要仅凭 `theme.yaml` 的版本约束推断安装环境具备商城能力。

发布前把安装包安装到干净的目标版本实例中验证，避免本地开发目录中的额外文件掩盖缺失资源。升级 Halo 后，优先对照[版本差异](https://docs.halo.run/developer-guide/shop/theme/api-changelog.md)，复测被主题覆盖的模板和交易流程。