入门#

此文档将帮助你了解如何构建你的第一个插件并在 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。

#运行插件

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

# macOS / Linux
./gradlew haloServer

# Windows
./gradlew.bat haloServer

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

# macOS / Linux
./gradlew build

# Windows
./gradlew.bat build

# 进入 Halo 项目根目录后，使用 cd 命令进入配置文件目录
cd application/src/main/resources

# 创建 application-local.yaml 文件
touch application-local.yaml

# 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

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

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

#下一步

• 了解插件项目的完整组成：目录结构
• 跟随完整案例开发一个具有前后端的插件：Todo List 插件
• 查阅可用的扩展能力：扩展点和定制化