在本地搭建 Halo 插件开发环境

6 阅读

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

使用脚手架创建插件项目

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

前提条件

创建步骤

在终端执行：

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 守护进程正在运行）

  • 已安装 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，确认插件已出现在插件列表中且功能正常。

如何选择

方式 优点 适用场景
Gradle haloServer 无需维护 Halo 源码；环境与官方容器一致；上手快 日常插件功能与 UI 开发（推荐默认）
Halo 源码 + fixed-plugin-path 可调试核心与插件联动；不依赖 Docker 无法使用 Docker，或需要修改/调试 Halo 本体

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

评论