在本地环境运行 Halo 源码

6 阅读

概览

完整运行一个 Halo 开发环境需要同时启动两个部分：

  • 后端（Halo 主项目）：halo-dev/halo，提供 API 和业务逻辑；

  • 前端（UI）：托管在 Halo 主项目的 ui 目录，包含 Console 管理控制台和 UC 个人中心。

Halo 主项目不会将 UI 的构建产物纳入 Git 版本控制，因此开发时需要在本地单独启动 UI 开发服务。正式发布时，CI 会自动完成 UI 的构建和打包。

第一步：准备开发环境

JDK 21

后端基于 Java 21 构建，推荐使用 Eclipse Temurin 发行版。

  • macOS / Linux

    # 推荐使用 SDKMAN 管理 JDK 版本，如已安装可略过
curl -s "https://get.sdkman.io" | bash

# 安装 JDK 21
sdk install java 21-tem

  • Windows

    前往 https://adoptium.net 下载 JDK 21 安装包，按向导安装即可。

安装完成后验证：

java -version
# openjdk version "21.x.x" ...

Node.js 24

推荐按照 Node.js 的官方下载页面的指引进行安装：https://nodejs.org/zh-cn/download

安装完成后验证：

node -v
# v24.x.x

pnpm

前端包管理器使用 pnpm，推荐通过 Corepack 启用：

corepack enable pnpm

或者通过 npm 安装：

npm install -g pnpm

IntelliJ IDEA

后端推荐使用 IntelliJ IDEA 开发，社区版（Community Edition）即可满足需求，免费使用。

前往 https://www.jetbrains.com/idea/download 下载安装。

第二步：克隆项目

# HTTPS
git clone https://github.com/halo-dev/halo

# SSH（推荐）
git clone git@github.com:halo-dev/halo.git

# GitHub CLI
gh repo clone halo-dev/halo

如果你已经 Fork 了仓库，将以上命令中的 halo-dev 替换为你的 GitHub 用户名即可。

第三步：启动 UI 开发服务

cd path/to/halo/ui
pnpm install
pnpm build:packages
pnpm dev

看到以下输出表示 UI 服务已正常启动：

VITE v8.0.0  ready in 805 ms

➜  Local:   http://localhost:3000/
➜  Network: http://192.168.1.7:3000/

注意：请勿直接通过 http://localhost:3000 访问，会因跨域限制导致无法登录。应通过后端代理地址访问，详见下方说明。

第四步：运行 Halo 后端

使用 IntelliJ IDEA

  1. 用 IntelliJ IDEA 打开 Halo 项目根目录，等待 Gradle 完成初始化和依赖下载；

  2. （可选）下载预设插件：

     # macOS / Linux
 ./gradlew downloadPluginPresets

 # Windows
 ./gradlew.bat downloadPluginPresets

  3. 修改运行配置中的 Active Profiles：

    • macOS / Linux：设置为 dev

    • Windows：设置为 dev,win

  4. 点击运行按钮，等待启动完成。

使用 Gradle 命令行

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

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

访问地址

后端启动后，UI 请求会通过 dev 配置中的代理转发到 http://localhost:3000，因此统一通过以下地址访问：

页面

地址

网站首页

http://localhost:8090

Console 控制台

http://localhost:8090/console

UC 个人中心

http://localhost:8090/uc

代理配置位于 dev Profile 的配置文件中，内容如下：

halo:
  ui:
    proxy:
      endpoint: http://localhost:3000/
      enabled: true

评论