插件注册和配置

在 Halo 插件开发中，plugin.yaml 是用于定义插件基本信息和配置的核心文件。

一个典型的 plugin.yaml 文件如下所示：

apiVersion: plugin.halo.run/v1alpha1
kind: Plugin
metadata:
  name: hello-world
spec:
  requires: ">=2.0.0"
  author:
    name: Halo
    website: https://www.halo.run
  logo: https://www.halo.run/logo
  # settingName: hello-world-settings
  # configMapName: hello-world-configmap
  homepage: https://github.com/halo-dev/plugin-starter#readme
  repo: https://github.com/halo-dev/plugin-starter
  issues: https://github.com/halo-dev/plugin-starter/issues
  displayName: "插件 Hello world"
  description: "插件开发的 hello world，用于学习如何开发一个简单的 Halo 插件"
  license:
    - name: "GPL-3.0"
      url: "https://github.com/halo-dev/plugin-starter/blob/main/LICENSE"

字段详解

字段	说明
`apiVersion` 和 `kind`	固定写法，定义插件的 API 版本和类型，不可更改。
`metadata.name`	插件的唯一标识名，长度不超过 253 个字符，仅包含小写字母、数字或 `-`，以字母或数字开头和结尾。
`spec.enabled`	Halo 运行时记录的期望启用状态。普通上传安装会将其设为 `false`，不能通过源清单让插件在安装后自动启用，通常无需在源文件中声明。
`spec.version`	插件版本，必须为完整的 SemVer 版本号。使用官方 Gradle 插件构建时，最终产物中的值会自动取自 Gradle 项目版本。
`spec.requires`	插件支持的 Halo 版本范围，遵循 SemVer Range Expressions。参考：常用 SemVer Range Expressions
`spec.pluginDependencies`	插件依赖及其版本范围，支持必需依赖和可选依赖。参考：依赖其他插件。
`spec.author`	插件作者的信息，包括名称和支持网址。
`spec.logo`	插件的 logo，支持 URL 链接或相对于项目 `src/main/resources` 目录的文件路径。
`spec.settingName`（可选）	插件配置表单的名称，用于提供用户可视化配置的表单，名称建议为 "插件名-settings"。参考：插件设置与表单组件、表单定义与组件速查和获取插件配置。
`spec.configMapName`（可选）	插件配置存储的 ConfigMap 名称，通常建议命名为 "插件名-configmap"。没有配置 `settingName` 则不需要配置此项。
`spec.homepage`	插件的主页链接，通常指向插件的官方文档或帮助页面。
`spec.repo`	插件源码的仓库地址。
`spec.issues`	插件的反馈问题地址，可以是 GitHub Issues。
`spec.displayName`	插件的显示名称，它通常是以少数几个字来概括插件的用途。
`spec.description`	插件的简短描述，用于说明插件的用途。
`spec.license`	插件的许可协议，包含协议名称和链接。参考：Software License。

spec.version 由构建过程写入

Halo 的 Plugin Schema 要求最终安装包中的 spec.version 为完整的 SemVer 版本号。使用官方 Halo Gradle 插件时，源文件可以省略此字段；构建过程会读取 Gradle 项目版本，并将其写入构建产物中的 plugin.yaml。请不要手动修改构建目录里的副本。

settingName 需要对应资源

如果在 plugin.yaml 中配置了 settingName，但没有提供对应的 Setting 资源文件，插件将因为找不到 metadata.name 与 settingName 一致的 Setting 而无法启动。

从 @halo-dev/ui-plugin-bundler-kit@2.26.0 开始，spec.requires 也用于自动选择 UI 构建格式。支持的推导写法和回退行为请参考 UI 构建 > 输出格式与 Halo 目标。

插件运行模式

Halo 插件可以在两种模式下运行：deployment（默认）模式和 development 开发模式。

deployment 模式：标准的插件发布流程，插件打包成 JAR 文件后部署到 Halo。这是插件的生产运行模式。
development 模式：适用于插件开发阶段，开发者可以在无需打包和部署的情况下直接运行和调试插件，极大地提升了开发效率。

配置运行模式

要配置插件的运行模式，可以在 Halo 的配置文件中进行以下设置：

以 `deployment` 模式运行插件

默认情况下，Halo 以 deployment 模式运行插件，无需特别配置。如果需要明确指定，可以参考以下配置：

halo:
  plugin:
    runtime-mode: deployment

参考传统方式运行

以 `development` 模式运行插件

在开发过程中，可以将 runtime-mode 修改为 development，并通过 fixed-plugin-path 指定插件的绝对路径，支持多个路径配置：

# macOS / Linux
halo:
  plugin:
    runtime-mode: development
    fixed-plugin-path:
      # 配置为插件绝对路径
      - /path/to/halo-plugin-hello-world

# Windows
halo:
  plugin:
    runtime-mode: development
    fixed-plugin-path:
      # 配置为插件绝对路径
      - C:\path\to\halo-plugin-hello-world

development 模式的插件加载方式

development 开发模式下，既可以运行 fixed-plugin-path 下的插件，也可以运行通过 Console 管理端安装的 JAR 格式的插件。
如果使用 DevTools 运行方式来开发插件，则不需要配置 runtime-mode 和 fixed-plugin-path。

常用的 SemVer Range Expressions

常规符号：>、>=、<、<=、=、!=
通配符范围 ( * | X| x)：1.* 解释为 >=1.0.0 && <2.0.0
波形符范围 ( ~ )：~1.5 解释为 >=1.5.0 && <1.6.0
连字符范围 ( - )：1.0-2.0 解释为 >=1.0.0 && <=2.0.0
插入符范围 ( ^ )：^0.2.3解释为 >=0.2.3 && <0.3.0
部分版本范围：1 解释为 1.x 或 >=1.0.0 && <2.0.0
否定运算符：!(1.x) 解释为 <1.0.0 && >=2.0.0
带括号的表达式：~1.3 || (1.4.* && !=1.4.5) || ~2

更多详细信息请参考SemVer Range Expressions

插件注册和配置#

#字段详解

#插件运行模式

#配置运行模式

#以 deployment 模式运行插件

#以 development 模式运行插件