halo插件开发.jpg前言

这篇文章记录Halo插件开发环境搭建的过程，以及其中遇到的坑，包括Halo官方文档中有些步骤不够详细、没有提及的部分都统一记录在本文中。

由于Halo是一个前后端分离的项目，其运行环境也分为了两部分：前端运行环境、后端运行环境，并且搭建运行环境的方式也有两种：Docker运行以及传统方式运行，为了便于理解以及通用性，我这里主要介绍传统运行环境的搭建。

为了便于理解，本次教程中的目录结构如下：

📂 project
   📂 halo-main (halo前后端运行环境)
      📂 ui (halo前端服务)
      📂 ...
   📂 nuilli-halo-plugin (插件项目)
      📂...


创建插件项目

1. 创建项目

在终端中通过以下命令创建一个插件项目，我这里主要用的是 yarn 来创建

yarn create halo-plugin

当然你也可以使用其他包管理器来创建，具体命令可参考Halo官方插件模板的开源仓库：

https://github.com/halo-dev/create-halo-plugin/blob/main/README.zh-CN.md

# npm
npm create halo-plugin

# pnpm (推荐)
pnpm create halo-plugin

# npx
npx create-halo-plugin

执行上述命令后会出现CLI 引导提示，根据引导完成插件项目创建即可

yarn create v1.22.22
[1/4] Resolving packages...
[2/4] Fetching packages...
[3/4] Linking dependencies...
[4/4] Building fresh packages...

success Installed "create-halo-plugin@1.0.9" with binaries:
      - create-halo-plugin
🚀 Welcome to Halo Plugin Creator!

? Plugin name: » 这里填你的插件名
? Domain (for group and package name): » 这里填你的网站域名（如果没有可随便填一个）
? Author name: » 这里填作者名称


? Choose UI build tool: » - Use arrow-keys. Return to submit.
    Rsbuild
>   Vite - The Build Tool for the Web （这里是选择构建工具，通过键盘上下键选择，我这里选Vite）


📋 Project Configuration:
   Name: halo
   Domain: huib.top
   Package: huib.top.halo
   Author: huib6
   UI Tool: vite
   Output Directory: F:\新建文件夹\plugin-halo
? Create project? » (Y/n) 这里输入Y确认创建项目即可



2. 编译插件

传统运行环境下，插件需要预先编译后才能让Halo加载使用，在终端中通过以下命令编译插件

./gradlew.bat build

但这里有个坑，由于网络环境等因素可能会导致gradle的依赖包下载失败，从而导致插件编译失败，因此你可能需要编辑项目根目录下的 gradle/gradle-wrapper.properties 文件，内容如下：

distributionBase=GRADLE_USER_HOME
distributionPath=wrapper/dists
distributionUrl=https\://services.gradle.org/distributions/gradle-8.14-bin.zip
networkTimeout=10000
validateDistributionUrl=true
zipStoreBase=GRADLE_USER_HOME
zipStorePath=wrapper/dists
### 找到
distributionUrl=https\://services.gradle.org/distributions/gradle-8.14-bin.zip

### 替换为腾讯镜像源
distributionUrl=https://mirrors.cloud.tencent.com/gradle/gradle-8.14-bin.zip

完成这步之后重新使用插件编译命令重新编译插件即可




搭建运行环境

1. 下载Halo-dev

在github上将halo-dev项目克隆到本地，或者直接到halo的github仓库中下载并解压：

https://github.com/halo-dev/halo



2. 修改Halo配置文件

进入 项目根目录 /application/src/main/resources/ 这个文件夹中

然后创建一个 application-local.yaml 文件，如果有就忽略这一步，内容如下：

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


3. 构建前端项目

在Halo项目根目录下使用cd命令进入ui目录

cd ui
pnpm install
pnpm build:packages

启动前端项目

pnpm dev


4.启动后端项目

使用以下命令启动后端命令即可

./gradlew.bat downloadPluginPresets