跳到主要内容

入门

此文档将帮助你了解如何构建你的第一个插件并在 Halo 中安装和启用。

创建插件项目​

我们为插件开发者提供了一个插件创建工具，可以帮助你快速创建一个插件项目。

pnpm create halo-plugin
🚀 Welcome to Halo Plugin Creator!

✔ Plugin name: › hello-world
✔ Domain (for group and package name): › com.example
✔ Author name: › Halo
✔ Include UI project? › yes
✔ Choose UI build tool: › Vite

📋 Project Configuration:
   Name: hello-world
   Domain: com.example
   Package: com.example.helloworld
   Author: Halo
   Include UI: Yes
   UI Tool: vite
   Output Directory: /path/to/hello-world

✔ Create project? › yes
  • Plugin name: 插件的名称，用于插件的标识，此字段必须由小写字母、数字和连字符组成
  • Domain: 插件的包名
  • Author name: 插件的作者
  • Include UI project: 是否创建 Console 和 UC 的 UI 子项目；纯服务端插件可以选择不创建
  • Choose UI build tool: 插件的 UI 构建工具，目前支持 Vite（推荐）和 Rsbuild

更多关于插件创建工具的信息可查阅：halo-dev/create-halo-plugin

按需扩展项目​

从 create-halo-plugin 1.6.0 开始，可以在已有插件项目的根目录中按需添加 UI 项目或 Java 模块，无需重新创建插件或手动复制模板。

添加 UI 项目​

pnpm dlx create-halo-plugin@latest add ui --tool vite
# 或
pnpm dlx create-halo-plugin@latest add ui --tool rsbuild

命令会先展示将要创建或更新的文件；重复执行相同命令不会产生变化，已有的 ui/ 目录或无法识别的 Gradle 配置也不会被覆盖。UI 项目的构建方式可查阅：UI 构建。

添加 Java 模块​

pnpm dlx create-halo-plugin@latest add module api

可以将 api 替换为实际模块名。命令会创建 Java 源码与测试目录、Maven Central 发布配置、模块 README 和 .github/workflows/publish.yml，并自动配置模块依赖。发布工作流从 main 分支发布 SNAPSHOT 版本，从 v* 标签发布正式版本；运行前需要配置工作流中列出的 Maven Central 和签名密钥。

如果模块用于向其他插件提供 Java API，可继续阅读：发布共享 Java API。

运行插件​

现在有了一个空项目，我们需要让插件以最小配置运行起来，这里提供两种运行方式。

Halo 提供了一个用于插件开发的 DevTools，它可以帮助你快速的运行和调试插件，在模板插件项目中已经集成了 DevTools，可查阅 DevTools 使用说明。

使用 DevTools 运行插件的前提是需要你的电脑上已经安装了 Docker 环境，这是我们推荐的用户开发时运行插件的方式，只需要执行以下命令即可。

运行插件​

# macOS / Linux
./gradlew haloServer

# Windows
./gradlew.bat haloServer

执行此命令后，会自动创建一个 Halo 的 Docker 容器并加载当前的插件。

确认插件启动成功​

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

然后访问 http://localhost:8090/console

在插件列表将能看到插件已经被正确启动，并且在左侧菜单添加了一个 示例分组，其下有一个名 示例页面 的菜单。

图 1 确认插件启动成功
图 1 确认插件启动成功

下一步​