在本地开发 Halo 插件时，需要让 Halo 以开发模式加载你的插件项目。建议先用官方脚手架生成工程，再任选下面两种运行方式之一。

使用脚手架创建插件项目

官方提供 create-halo-plugin 脚手架，可在本机快速生成带 Gradle、前端构建与 DevTools 集成的插件模板。

前提条件

• 已安装 Node.js（建议 LTS）与 pnpm

创建步骤

在终端执行：

pnpm create halo-plugin

按交互提示填写即可，常见字段含义如下：

• Plugin name：插件标识，只能包含小写字母、数字和连字符

• Domain：用于 Java 包名与 group 的包域，例如 com.example

• Author name：作者展示名

• Choose UI build tool：控制台前端构建工具，可选 Rsbuild 或 Vite

命令结束后会生成一个独立目录，使用编辑器打开该目录即可开始开发。

方式一：使用 Halo Gradle 插件（推荐）

通过上述脚手架创建的项目已集成 DevTools。在插件项目根目录执行 haloServer 任务时，Gradle 会拉起一个用于插件开发的 Halo 容器，并把当前工程作为插件挂载进去。

前提条件

• 已安装 Docker（并保证 Docker 守护进程正在运行）

  • macOS：推荐安装 OrbStack（轻量、启动快）或 Docker Desktop

  • Windows：推荐安装 Docker Desktop

  • Linux：参考 Docker 官方安装文档

• 已安装 JDK 21

  • macOS / Linux

    # 推荐使用 SDKMAN 管理 JDK 版本，如已安装可略过
    curl -s "https://get.sdkman.io" | bash
    
    # 安装 JDK 21
    sdk install java 21-tem

  • Windows

    前往 https://adoptium.net 下载 JDK 21 安装包，按向导安装即可。

步骤

在插件项目根目录执行：

 # macOS / Linux
 ./gradlew haloServer

 # Windows
 ./gradlew.bat haloServer

首次拉取镜像可能需要一些时间。启动成功后，控制台会打印默认访问地址与账号密码，例如：

 Halo 初始化成功，访问：http://localhost:8090/console
 用户名：admin
 密码：admin

浏览器打开控制台，在插件列表中应能看到当前插件已加载；修改代码后按 DevTools 文档说明进行热更新或重新构建即可。

该方式不需要在本机单独克隆、编译 Halo 主仓库，环境一致性好，适合绝大多数插件开发场景。

方式二：本地运行 Halo 源码并指定插件目录

当本机无法使用 Docker，或你需要同时调试 Halo 核心与插件行为时，可以在本地从源码启动 Halo，并通过配置把插件目录固定为开发路径。

前提条件

• 已按 Halo 开发环境运行 在本机成功运行 Halo 源码工程

• 已有一个可用的插件项目（通常由脚手架创建），且能通过 ./gradlew build 正常产出插件包

步骤

在插件项目中先完成一次构建：

 # macOS / Linux
 ./gradlew build

 # Windows
 ./gradlew.bat build

在 Halo 工程 application/src/main/resources 下创建或编辑 application-local.yaml，增加插件开发模式与固定路径（路径改为你的插件项目根目录的绝对路径）：

 halo:
   plugin:
     runtime-mode: development
     fixed-plugin-path:
       - /path/to/your-plugin-project

Windows 示例：

halo:
  plugin:
    runtime-mode: development
    fixed-plugin-path:
      - C:\path\to\your-plugin-project

在 Halo 仓库根目录启动（与官方文档中的 profile 保持一致）：

# macOS / Linux
./gradlew bootRun --args="--spring.profiles.active=dev,local"

# Windows
gradlew.bat bootRun --args="--spring.profiles.active=dev,win,local"

访问 http://localhost:8090/console，确认插件已出现在插件列表中且功能正常。

如何选择

更多关于 Halo 插件开发的文档可查阅：Halo 文档 - 插件开发