> 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. # 开发者指南 ## 系统开发 ### [准备工作](/developer-guide/core/prepare.md) - [环境要求](/developer-guide/core/prepare.md#环境要求) - [名词解释](/developer-guide/core/prepare.md#名词解释) ### [开发环境运行](/developer-guide/core/run.md) - [项目结构说明](/developer-guide/core/run.md#项目结构说明) - [克隆项目](/developer-guide/core/run.md#克隆项目) - [运行 UI 服务](/developer-guide/core/run.md#运行-ui-服务) - [运行 Halo](/developer-guide/core/run.md#运行-halo) ### [构建](/developer-guide/core/build.md) - [克隆项目](/developer-guide/core/build.md#克隆项目) - [构建 Fat Jar](/developer-guide/core/build.md#构建-fat-jar) - [构建 Docker 镜像](/developer-guide/core/build.md#构建-docker-镜像) ### [Halo 架构概览](/developer-guide/core/framework.md) - [Halo 核心概念和 Extension](/developer-guide/core/framework.md#halo-核心概念和-extension) ## 插件开发 ### [介绍](/developer-guide/plugin/introduction.md) ### [准备工作](/developer-guide/plugin/prepare.md) ### [AI 辅助](/developer-guide/plugin/ai.md) - [提供文档上下文](/developer-guide/plugin/ai.md#提供文档上下文) - [核对版本与源码](/developer-guide/plugin/ai.md#核对版本与源码) - [生成前检查清单](/developer-guide/plugin/ai.md#生成前检查清单) - [Agent Skill](/developer-guide/plugin/ai.md#agent-skill) ### [入门](/developer-guide/plugin/hello-world.md) - [创建插件项目](/developer-guide/plugin/hello-world.md#创建插件项目) - [按需扩展项目](/developer-guide/plugin/hello-world.md#按需扩展项目) - [运行插件](/developer-guide/plugin/hello-world.md#运行插件) - [下一步](/developer-guide/plugin/hello-world.md#下一步) ### [案例和最佳实践](/developer-guide/plugin/examples/index.md) ### [基础](/developer-guide/plugin/basics/index.md) ### [API 参考](/developer-guide/plugin/api-reference/index.md) ### [扩展点和定制化](/developer-guide/plugin/extension-points/index.md) ### [与其他插件交互](/developer-guide/plugin/interaction/index.md) ### [与主题集成](/developer-guide/plugin/theme-integration.md) - [选择集成方式](/developer-guide/plugin/theme-integration.md#选择集成方式) - [提供稳定的模板契约](/developer-guide/plugin/theme-integration.md#提供稳定的模板契约) - [提供浏览器 API 和资源](/developer-guide/plugin/theme-integration.md#提供浏览器-api-和资源) - [扩展最终页面输出](/developer-guide/plugin/theme-integration.md#扩展最终页面输出) - [验证集成状态](/developer-guide/plugin/theme-integration.md#验证集成状态) ### [安全和权限管理](/developer-guide/plugin/security/index.md) ### [测试插件](/developer-guide/plugin/testing.md) - [选择验证层级](/developer-guide/plugin/testing.md#选择验证层级) - [运行自动化检查](/developer-guide/plugin/testing.md#运行自动化检查) - [在本地 Halo 中联调](/developer-guide/plugin/testing.md#在本地-halo-中联调) - [验证兼容性和生命周期](/developer-guide/plugin/testing.md#验证兼容性和生命周期) - [记录可复核结果](/developer-guide/plugin/testing.md#记录可复核结果) ### [常见问题](/developer-guide/plugin/faq.md) - [插件启动失败](/developer-guide/plugin/faq.md#startup-failure) - [类加载与依赖冲突](/developer-guide/plugin/faq.md#dependency-conflict) - [UI 扩展不加载](/developer-guide/plugin/faq.md#ui-not-loading) - [权限配置不生效](/developer-guide/plugin/faq.md#permission-not-effective) - [开发期热重载不生效](/developer-guide/plugin/faq.md#hot-reload) ### [插件发布验收清单](/developer-guide/plugin/release-checklist.md) - [构建发布制品](/developer-guide/plugin/release-checklist.md#构建发布制品) - [检查 JAR 内容](/developer-guide/plugin/release-checklist.md#检查-jar-内容) - [验证安装和升级](/developer-guide/plugin/release-checklist.md#验证安装和升级) - [核对 CI/CD](/developer-guide/plugin/release-checklist.md#核对-cicd) - [记录发布证据](/developer-guide/plugin/release-checklist.md#记录发布证据) ### [API 变更日志](/developer-guide/plugin/api-changelog.md) - [2.26.0](/developer-guide/plugin/api-changelog.md#2260) - [2.25.0](/developer-guide/plugin/api-changelog.md#2250) - [2.23.0](/developer-guide/plugin/api-changelog.md#2230) - [2.22.8](/developer-guide/plugin/api-changelog.md#2228) - [2.22.5](/developer-guide/plugin/api-changelog.md#2225) - [2.22.1](/developer-guide/plugin/api-changelog.md#2221) - [2.22.0](/developer-guide/plugin/api-changelog.md#2220) ## 主题开发 ### [准备工作](/developer-guide/theme/prepare.md) - [搭建开发环境](/developer-guide/theme/prepare.md#搭建开发环境) - [新建一个主题](/developer-guide/theme/prepare.md#新建一个主题) - [通过模板创建](/developer-guide/theme/prepare.md#通过模板创建) - [创建第一个页面模板](/developer-guide/theme/prepare.md#创建第一个页面模板) - [安装主题](/developer-guide/theme/prepare.md#安装主题) ### [AI 辅助](/developer-guide/theme/ai.md) - [提供文档上下文](/developer-guide/theme/ai.md#提供文档上下文) - [核对版本与源码](/developer-guide/theme/ai.md#核对版本与源码) - [生成前检查清单](/developer-guide/theme/ai.md#生成前检查清单) - [Agent Skill](/developer-guide/theme/ai.md#agent-skill) ### [目录结构](/developer-guide/theme/structure.md) ### [配置文件](/developer-guide/theme/config.md) - [格式示例](/developer-guide/theme/config.md#格式示例) - [字段详解](/developer-guide/theme/config.md#字段详解) - [更新配置](/developer-guide/theme/config.md#更新配置) - [从 1.x 迁移](/developer-guide/theme/config.md#从-1x-迁移) ### [Thymeleaf 模板语法](/developer-guide/theme/thymeleaf.md) - [确认运行环境](/developer-guide/theme/thymeleaf.md#确认运行环境) - [认识常用表达式](/developer-guide/theme/thymeleaf.md#认识常用表达式) - [输出文本和 HTML](/developer-guide/theme/thymeleaf.md#输出文本和-html) - [组合文本和处理空值](/developer-guide/theme/thymeleaf.md#组合文本和处理空值) - [遍历和条件渲染](/developer-guide/theme/thymeleaf.md#遍历和条件渲染) - [定义局部变量](/developer-guide/theme/thymeleaf.md#定义局部变量) - [复用模板片段](/developer-guide/theme/thymeleaf.md#复用模板片段) - [使用表达式工具](/developer-guide/theme/thymeleaf.md#使用表达式工具) - [向 JavaScript 输出数据](/developer-guide/theme/thymeleaf.md#向-javascript-输出数据) - [常见错误](/developer-guide/theme/thymeleaf.md#常见错误) - [排查模板错误](/developer-guide/theme/thymeleaf.md#排查模板错误) ### [静态资源](/developer-guide/theme/static-resources.md) - [模板标签引用](/developer-guide/theme/static-resources.md#模板标签引用) - [API 引用](/developer-guide/theme/static-resources.md#api-引用) - [#theme.route(path)](/developer-guide/theme/static-resources.md#themeroutepath) ### [设置选项](/developer-guide/theme/settings.md) - [区分系统设置与主题设置](/developer-guide/theme/settings.md#区分系统设置与主题设置) - [定义表单](/developer-guide/theme/settings.md#定义表单) - [更新配置](/developer-guide/theme/settings.md#更新配置) - [从 1.x 迁移](/developer-guide/theme/settings.md#从-1x-迁移) ### [主题附带资源](/developer-guide/theme/extension-resources.md) - [提供资源](/developer-guide/theme/extension-resources.md#提供资源) - [允许的资源](/developer-guide/theme/extension-resources.md#允许的资源) - [加载和更新](/developer-guide/theme/extension-resources.md#加载和更新) - [卸载边界](/developer-guide/theme/extension-resources.md#卸载边界) - [源码参考](/developer-guide/theme/extension-resources.md#源码参考) ### [国际化](/developer-guide/theme/i18n.md) - [定义消息](/developer-guide/theme/i18n.md#定义消息) - [在模板中使用](/developer-guide/theme/i18n.md#在模板中使用) - [页面级消息](/developer-guide/theme/i18n.md#页面级消息) - [在 JavaScript 中使用](/developer-guide/theme/i18n.md#在-javascript-中使用) - [切换和测试语言](/developer-guide/theme/i18n.md#切换和测试语言) ### [模板路由](/developer-guide/theme/template-route-mapping.md) - [主要模板](/developer-guide/theme/template-route-mapping.md#主要模板) - [自定义模板](/developer-guide/theme/template-route-mapping.md#custom-templates) ### [全局变量](/developer-guide/theme/global-variables.md) - [site](/developer-guide/theme/global-variables.md#site) - [#halo.matchVersion(constraint)](/developer-guide/theme/global-variables.md#halomatchversionconstraint) - [theme](/developer-guide/theme/global-variables.md#theme) - [按登录状态条件渲染](/developer-guide/theme/global-variables.md#按登录状态条件渲染) - [访问量统计脚本](/developer-guide/theme/global-variables.md#访问量统计脚本) ### [页面模板与变量](/developer-guide/theme/template-variables/index.md) ### [Finder API](/developer-guide/theme/finder-apis/index.md) ### [自定义标签](/developer-guide/theme/template-tag.md) - [halo:comment](/developer-guide/theme/template-tag.md#halocomment) - [halo:footer](/developer-guide/theme/template-tag.md#halofooter) ### [模型元数据](/developer-guide/theme/annotations.md) - [#annotations.get(extension,key)](/developer-guide/theme/annotations.md#annotationsgetextensionkey) - [#annotations.getOrDefault(extension,key,defaultValue)](/developer-guide/theme/annotations.md#annotationsgetordefaultextensionkeydefaultvalue) - [#annotations.contains(extension,key)](/developer-guide/theme/annotations.md#annotationscontainsextensionkey) ### [使用 Vite 开发主题](/developer-guide/theme/vite.md) - [区分源码和构建产物](/developer-guide/theme/vite.md#区分源码和构建产物) - [配置插件](/developer-guide/theme/vite.md#配置插件) - [复用模板片段](/developer-guide/theme/vite.md#复用模板片段) - [开发和构建](/developer-guide/theme/vite.md#开发和构建) ### [与插件集成](/developer-guide/theme/plugin-integration.md) - [检查插件是否可用](/developer-guide/theme/plugin-integration.md#检查插件是否可用) - [保留主题扩展点](/developer-guide/theme/plugin-integration.md#保留主题扩展点) - [兼容插件前台页面](/developer-guide/theme/plugin-integration.md#兼容插件前台页面) - [适配插件组件配色](/developer-guide/theme/plugin-integration.md#适配插件组件配色) - [覆盖插件前台模板](/developer-guide/theme/plugin-integration.md#覆盖插件前台模板) - [验证兼容性](/developer-guide/theme/plugin-integration.md#验证兼容性) ### [页面布局契约](/developer-guide/theme/page-layout.md) - [适配主题布局](/developer-guide/theme/page-layout.md#适配主题布局) - [在主题页面中复用布局](/developer-guide/theme/page-layout.md#在主题页面中复用布局) - [插件页面调用布局](/developer-guide/theme/page-layout.md#插件页面调用布局) - [兼容状态](/developer-guide/theme/page-layout.md#兼容状态) - [版本演进](/developer-guide/theme/page-layout.md#版本演进) ### [UI 扩展](/developer-guide/theme/ui-plugin.md) - [目录结构](/developer-guide/theme/ui-plugin.md#目录结构) - [入口文件](/developer-guide/theme/ui-plugin.md#入口文件) - [使用 Vite 构建](/developer-guide/theme/ui-plugin.md#使用-vite-构建) - [使用 Rsbuild 构建](/developer-guide/theme/ui-plugin.md#使用-rsbuild-构建) - [输出格式和共享依赖](/developer-guide/theme/ui-plugin.md#输出格式和共享依赖) ### [主题调试与测试](/developer-guide/theme/testing.md) - [建立开发反馈循环](/developer-guide/theme/testing.md#建立开发反馈循环) - [定位常见问题](/developer-guide/theme/testing.md#定位常见问题) - [覆盖页面和状态](/developer-guide/theme/testing.md#覆盖页面和状态) - [记录可复核结果](/developer-guide/theme/testing.md#记录可复核结果) ### [图片优化](/developer-guide/theme/image-optimization.md) - [为什么使用响应式图片？](/developer-guide/theme/image-optimization.md#为什么使用响应式图片) - [Finder API](/developer-guide/theme/image-optimization.md#finder-api) - [HTTP API](/developer-guide/theme/image-optimization.md#http-api) ### [性能最佳实践](/developer-guide/theme/performance.md) - [静态资源加载](/developer-guide/theme/performance.md#静态资源加载) - [控制 Finder 调用](/developer-guide/theme/performance.md#控制-finder-调用) - [图片优化](/developer-guide/theme/performance.md#图片优化) - [验证](/developer-guide/theme/performance.md#验证) ### [主题 SEO](/developer-guide/theme/seo.md) - [设置页面标题](/developer-guide/theme/seo.md#设置页面标题) - [使用 Halo 注入的元数据](/developer-guide/theme/seo.md#使用-halo-注入的元数据) - [通过主题设置控制扩展标签](/developer-guide/theme/seo.md#通过主题设置控制扩展标签) - [可选的结构化数据](/developer-guide/theme/seo.md#可选的结构化数据) - [验证最终结果](/developer-guide/theme/seo.md#验证最终结果) ### [构建与打包](/developer-guide/theme/packaging.md) - [配置打包命令](/developer-guide/theme/packaging.md#配置打包命令) - [默认打包内容](/developer-guide/theme/packaging.md#默认打包内容) - [谨慎使用 --all](/developer-guide/theme/packaging.md#谨慎使用---all) - [发布前检查](/developer-guide/theme/packaging.md#发布前检查) ### [主题发布验收清单](/developer-guide/theme/release-checklist.md) - [构建并确认制品](/developer-guide/theme/release-checklist.md#构建并确认制品) - [验证安装和升级](/developer-guide/theme/release-checklist.md#验证安装和升级) - [覆盖页面和内容状态](/developer-guide/theme/release-checklist.md#覆盖页面和内容状态) - [验证集成和浏览器表现](/developer-guide/theme/release-checklist.md#验证集成和浏览器表现) - [配置持续发布（可选）](/developer-guide/theme/release-checklist.md#配置持续发布可选) - [记录发布证据](/developer-guide/theme/release-checklist.md#记录发布证据) ### [API 变更日志](/developer-guide/theme/api-changelog.md) - [2.26.0](/developer-guide/theme/api-changelog.md#2260) - [2.25.0](/developer-guide/theme/api-changelog.md#2250) - [2.24.1](/developer-guide/theme/api-changelog.md#2241) - [2.23.0](/developer-guide/theme/api-changelog.md#2230) - [2.22.8](/developer-guide/theme/api-changelog.md#2228) - [2.22.1](/developer-guide/theme/api-changelog.md#2221) - [2.22.0](/developer-guide/theme/api-changelog.md#2220) ## RESTful API ### [介绍](/developer-guide/restful-api/introduction.md) - [API 在线文档](/developer-guide/restful-api/introduction.md#api-在线文档) - [认证方式](/developer-guide/restful-api/introduction.md#认证方式) - [示例项目](/developer-guide/restful-api/introduction.md#示例项目) ### [API Client 请求库](/developer-guide/restful-api/api-client.md) - [安装](/developer-guide/restful-api/api-client.md#安装) - [模块介绍](/developer-guide/restful-api/api-client.md#模块介绍) - [使用](/developer-guide/restful-api/api-client.md#使用) ## 应用市场 ### [发布应用](/developer-guide/app-store/publish-app.md) - [发布流程概览](/developer-guide/app-store/publish-app.md#发布流程概览) - [发布前准备](/developer-guide/app-store/publish-app.md#发布前准备) - [申请成为开发者](/developer-guide/app-store/publish-app.md#申请成为开发者) - [创建应用和首个版本](/developer-guide/app-store/publish-app.md#创建应用和首个版本) - [提交首次审核](/developer-guide/app-store/publish-app.md#提交首次审核) - [审核期间和审核结果](/developer-guide/app-store/publish-app.md#审核期间和审核结果) - [发布后维护](/developer-guide/app-store/publish-app.md#发布后维护) ### [应用市场审核指南](/developer-guide/app-store/app-review-guidelines.md) - [提交前检查](/developer-guide/app-store/app-review-guidelines.md#提交前检查) - [1. 安全](/developer-guide/app-store/app-review-guidelines.md#1-安全) - [2. 性能](/developer-guide/app-store/app-review-guidelines.md#2-性能) - [3. 商业](/developer-guide/app-store/app-review-guidelines.md#3-商业) - [4. 设计](/developer-guide/app-store/app-review-guidelines.md#4-设计) - [5. 法律](/developer-guide/app-store/app-review-guidelines.md#5-法律) - [重新提交与申诉](/developer-guide/app-store/app-review-guidelines.md#重新提交与申诉) - [指南更新](/developer-guide/app-store/app-review-guidelines.md#指南更新) - [联系方式](/developer-guide/app-store/app-review-guidelines.md#联系方式) ## 表单定义与组件速查 ### [表单定义与组件速查](/developer-guide/form-schema.md) - [选择正确的使用场景](/developer-guide/form-schema.md#选择正确的使用场景) - [常用 FormKit 原生输入](/developer-guide/form-schema.md#常用-formkit-原生输入) - [Setting 资源定义方式](/developer-guide/form-schema.md#setting-资源定义方式) - [Halo 扩展组件速查](/developer-guide/form-schema.md#halo-扩展组件速查) - [组件类型](/developer-guide/form-schema.md#组件类型) ## 元数据表单定义 ### [元数据表单定义](/developer-guide/annotations-form.md) - [AnnotationSetting 资源定义方式](/developer-guide/annotations-form.md#annotationsetting-资源定义方式) - [为多个模型定义表单](/developer-guide/annotations-form.md#为多个模型定义表单)