KnowSphere 主题开发文档

适用于 Halo 2.26.0+。核对日期：2026-11-05。面向为 KnowSphere 免费 Base、市场版 Base 或 Pro 开发适配主题的开发者。

从这里开始

  1. 快速上手：加载资源、渲染已过滤内容并接入会员与签到。
  2. 主题脚手架：主题目录、片段和自定义页面。
  3. API 速览：Finder、公开接口与用户中心接口的边界。
  4. 速查表：常用模板、样式和请求处理。
  5. FAQ：空数据、资源重复、路由和权限问题。

完整目录

版本边界

能力免费 Base / 市场版 BasePro
内容访问控制、会员、订单、钱包、优惠券、签到积分支持支持
基础专栏、自定义评论区、支付订单导出、活动礼包支持支持
分销、任务、商城、多作者、开放 API 等独立业务不提供以安装版本、授权及实际功能设置为准
自动续费等计划中能力不承诺不把配置字段或路线图当作已实现能力

基础专栏、评论区和支付订单导出不能标为 Pro 专属。市场版不通过修改配置解锁独立 Pro 业务。getPluginInfo().pro 只说明版本，不代表每项功能都已启用；主题也不能授予权限。

关键约定

  • getPluginInfo() 同步返回对象；Mono 用 .block()，Flux 用 .collectList().block()。分页的 Mono<ListResult<...>> 要读取 .items。
  • 读取服务端提供的 permalink 和 Finder 资源 URL，不拼接文章路由或 know-sphere-pro 文件名。
  • 插件通常自动注入主题资源；手动引入只用于未注入的特殊场景，不能重复加载。
  • 付费内容使用 Halo 输出的已处理正文；不能把隐藏正文装进脚本、属性、JSON 或 CSS 隐藏区。
  • 登录用户的订单、会员、优惠券和付费内容不能被跨用户页面缓存复用。
  • 公开预览和专栏不返回草稿、私密、内部、已删除或尚未发布文章；空数据应显示空态。

文档与技能维护

官方技能仓库仅公开主题接入文档、技能及维护脚本，不包含插件业务实现。可使用：

npx skills add wenjing-xin/knowsphere-theme-devlopment-skills --skill knowsphere-theme-dev

官网：主题开发文档。问题反馈使用技能仓库 Issues；产品支持见官网支持渠道。

上一篇 主题开发文档更新记录
下一篇 KnowSphere 主题 API 速览