> For AI agents: the complete documentation index is available at https://docs.halo.run/llms.txt, the full documentation bundle is available at https://docs.halo.run/llms-full.txt.

# 入门

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

## 创建插件项目

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

```bash
pnpm create halo-plugin
```

```text
🚀 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](https://github.com/halo-dev/create-halo-plugin)

## 按需扩展项目

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

### 添加 UI 项目

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

命令会先展示将要创建或更新的文件；重复执行相同命令不会产生变化，已有的 `ui/` 目录或无法识别的 Gradle 配置也不会被覆盖。UI 项目的构建方式可查阅：[UI 构建](https://docs.halo.run/developer-guide/plugin/basics/ui/build.md)。

### 添加 Java 模块

```bash
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](https://docs.halo.run/developer-guide/plugin/interaction/shared-java-api.md)。

## 运行插件

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


使用 DevTools 运行（推荐）

传统方式运行

Halo 提供了一个用于插件开发的 DevTools，它可以帮助你快速的运行和调试插件，在模板插件项目中已经集成了 DevTools，可查阅 [DevTools 使用说明](https://docs.halo.run/developer-guide/plugin/basics/devtools.md)。
使用 DevTools 运行插件的前提是需要你的电脑上已经安装了 Docker 环境，这是我们推荐的用户开发时运行插件的方式，只需要执行以下命令即可。

### 运行插件
```shell
# macOS / Linux
./gradlew haloServer

# Windows
./gradlew.bat haloServer
```
执行此命令后，会自动创建一个 Halo 的 Docker 容器并加载当前的插件。
### 确认插件启动成功
```text
Halo 初始化成功，访问：http://localhost:8090/console
用户名：admin
密码：admin
```
然后访问 `http://localhost:8090/console`
在插件列表将能看到插件已经被正确启动，并且在左侧菜单添加了一个 `示例分组`，其下有一个名 `示例页面` 的菜单。
![hello-world-in-plugin-list](/img/plugin-hello-world.png)

如果你的设备上无法安装 Docker 或你对 Docker 不熟悉，可以使用传统方式运行并开发插件。
但由于此方式需要先使用源码运行 Halo 才能启动插件，请确保已经在开发环境运行了 Halo，可以参考 [Halo 开发环境运行](https://docs.halo.run/developer-guide/core/run.md)

### 编译插件
```shell
# macOS / Linux
./gradlew build

# Windows
./gradlew.bat build
```
### 修改 Halo 配置文件
```shell
# 进入 Halo 项目根目录后，使用 cd 命令进入配置文件目录
cd application/src/main/resources

# 创建 application-local.yaml 文件
touch application-local.yaml
```
根据你的操作系统，将以下内容添加到 `application-local.yaml` 文件中。
```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
```
### 启动 Halo
```shell
# 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`
在插件列表将能看到插件已经被正确启动，并且在左侧菜单添加了一个 `示例分组`，其下有一个名 `示例页面` 的菜单。
![hello-world-in-plugin-list](/img/plugin-hello-world.png)

## 


## 下一步

- 了解插件项目的完整组成：[目录结构](https://docs.halo.run/developer-guide/plugin/basics/structure.md)
- 跟随完整案例开发一个具有前后端的插件：[Todo List 插件](https://docs.halo.run/developer-guide/plugin/examples/todolist.md)
- 查阅可用的扩展能力：[扩展点和定制化](https://docs.halo.run/developer-guide/plugin/extension-points/index.md)