KnowSphere 主题开发 FAQ

页面提示 Finder 不存在

确认 Halo 2.26.0+、插件已启用且启动成功。主题应在可选插件条件块内调用 Finder，插件未安装时保留普通主题页面。不要认为所有主题运行时都提供相同的自定义全局变量。

重复弹窗、事件执行两次

检查主题是否在自动注入外又手动加载一次组件脚本。优先保留自动注入。切页时清理自己注册的事件和定时器。

订单循环报错或一直为空

listMyOrders() 返回 Mono 分页对象，列表在 items；先 .block() 再检查 result 和 items。匿名不应显示账号 A 的缓存订单。检查请求有没有被登录页重定向，并检查响应 content-type。

套餐标题不显示

MembershipPlanVo 的字段是 title。不要把它与 ColumnVo.displayName 混用。查阅 Finder 字段。

有组件但主题 CSS 无效

Web Components 使用 Shadow DOM；通过公开 CSS 变量调整。普通后代选择器不能穿透。暗色变量放在 html.dark 或主题实际暗色选择器中。

为什么看不到草稿或定时章节

公开预览、章节和 Finder 会过滤未公开数据。不要用管理 API 绕过，也不要在浏览器预取原始快照。Base 基础专栏与 Pro 学习进度/滴灌功能不是同一项能力。

评论成功却没有立刻解锁

需要实际成功提交浏览器的 HttpOnly 凭证，且评论已审核、未隐藏、未删除。检查同源 Cookie、HTTPS、站点匿名评论和审核设置。仅传邮箱的补签请求被拒绝属于预期行为。旧版邮箱凭证不再有效。

为什么没有美元和通知开关

当前实现的支付链路按 CNY 结算，遗留 USD 配置归一为 CNY，不进行汇率换算。尚未实现的订单通知和到期提醒设置已移除。不要通过主题增加无后端能力的开关。

支付配置不再显示原私钥

已配置占位值不是密钥；保留占位值或留空可保留旧密钥，输入新值替换。迁移站点需同时恢复数据库与 .knowsphere/payment-credentials.key。不要把该文件提交 Git 或通过反馈上传。

买完还是不能读

先确认订单的服务端支付及完成状态，再检查集合购买目标、会员有效期、浏览器登录身份和缓存。前端弹框关闭或支付事件不能证明收款成功。真实资金问题由商户到对应渠道核对。

主题接入文档问题：技能仓库 Issues。产品问题：支持表单。