Halo 2.11开发环境搭建实战手册从环境配置到联调优化第一次接触Halo开源项目时我被它优雅的设计理念所吸引——一个现代化的Java博客系统却融合了前后端分离架构的灵活性和单体应用的部署便利性。但真正开始搭建开发环境时才发现要同时运行主项目和UI服务并非想象中那么简单特别是跨域问题这个隐形杀手让不少开发者栽了跟头。本文将带你从零开始用最接地气的方式完成整个开发环境的搭建。1. 开发环境准备构建稳固基石在开始Halo开发之旅前我们需要确保本地环境满足基本要求。不同于简单的运行环境开发环境需要更精细的版本控制。核心组件清单OpenJDK 17 LTSHalo 2.11基于Spring Boot 3.x构建必须使用JDK 17Node.js 20 LTSUI部分采用现代前端技术栈pnpm 9比npm/yarn更高效的依赖管理工具Git代码版本控制必备IntelliJ IDEA推荐使用2023.1版本对Gradle支持更完善提示环境变量配置是新手常忽略的点特别是JAVA_HOME和PATH的设置。验证Java环境是否正确java -version javac -version版本兼容性矩阵组件最低版本推荐版本备注JDK17.0.217.0.8长期支持版Node18.12.020.9.0偶数版更稳定pnpm8.6.09.0.5必须≥8.0安装完成后建议执行以下命令验证环境node -v pnpm -v git --version2. 项目初始化从克隆到结构解析Halo项目采用多模块设计理解项目结构对后续开发至关重要。不同于简单克隆就能运行的项目Halo需要同时管理主项目和UI子项目。克隆项目的最佳实践# 使用SSH方式克隆推荐开发者 git clone gitgithub.com:halo-dev/halo.git cd halo项目目录结构深度解析halo ├── application # 主模块Spring Boot入口 ├── common # 公共模块 ├── framework # 框架核心 ├── infra # 基础设施 ├── plugins # 插件系统 └── ui # 前端项目ConsoleUC特别需要注意的是从2.11版本开始UI目录同时包含Console管理后台运行在3000端口UC用户中心运行在4000端口注意开发环境下UI资源不会自动构建到主项目这与生产环境不同必须同时运行两个服务。3. UI服务启动现代前端工具链实战进入ui目录你会看到一个典型的现代前端项目。Halo采用Vite 4构建相比Webpack有着更快的启动速度。启动UI服务的完整流程cd ui pnpm install # 安装依赖首次需要 pnpm build:packages # 构建基础包 pnpm dev # 启动开发服务器成功启动后控制台会显示VITE v4.2.3 ready in 638 ms ➜ Console: http://localhost:3000/console/ ➜ UC: http://localhost:4000/uc/常见问题排查依赖安装失败尝试删除node_modules和pnpm-lock.yaml后重新安装端口冲突修改vite.config.ts中的端口配置内存不足Node.js默认内存限制可能不够可设置NODE_OPTIONS--max-old-space-size40964. 主项目启动Spring Boot深度配置回到项目根目录我们需要配置IntelliJ IDEA来启动主项目。这里有几个关键点需要注意。Gradle初始配置打开IntelliJ IDEA选择Open导入项目等待Gradle自动初始化和依赖下载完成确保使用Gradle Wrapper推荐运行配置详解Windows用户Active Profiles设置为dev,win需要额外处理路径分隔符问题Mac/Linux用户Active Profiles只需设置为dev内存参数建议-Xmx1024m命令行启动方案# Mac/Linux ./gradlew bootRun --args--spring.profiles.activedev # Windows gradlew.bat bootRun --args--spring.profiles.activedev,win成功启动后控制台会输出Started Application in 5.302 seconds5. 跨域问题终极解决方案这是大多数开发者遇到的第一个真正的挑战。由于UI服务运行在3000/4000端口而主API在8090端口浏览器会阻止这种跨域请求。Halo的代理配置原理 主项目的application-dev.yml中已经预设了代理规则halo: console: proxy: endpoint: http://localhost:3000/ enabled: true uc: proxy: endpoint: http://localhost:4000/ enabled: true正确访问方式管理后台http://localhost:8090/console用户中心http://localhost:8090/uc主站APIhttp://localhost:8090/api调试技巧使用浏览器开发者工具检查Network请求确认请求是否被正确代理检查响应头是否包含Access-Control-Allow-Origin6. 开发模式下的高效工作流建立了完整环境后如何高效开发是关键。Halo的多模块设计需要特定的工作流程。热重载配置前端Vite默认支持热更新后端Spring DevTools需要额外配置// build.gradle developmentOnly org.springframework.boot:spring-boot-devtools联调最佳实践先启动UI服务pnpm dev再启动主项目修改前端代码即时生效后端修改需要重启配置LiveReload可减少重启次数日志查看技巧tail -f ~/halo-next/logs/spring.log7. 进阶配置与性能调优当基础环境运行稳定后可以考虑进一步的优化配置。JVM参数调整 在IDEA的Run Configuration中添加-XX:UseG1GC -Xms512m -Xmx1024m -XX:MaxRAMPercentage75数据库切换 开发环境默认使用H2但可以改为MySQLspring: datasource: url: jdbc:mysql://localhost:3306/halo_dev username: root password: yourpassword缓存配置spring: cache: type: redis redis: host: localhost port: 63798. 常见问题与快速排错即使按照步骤操作仍可能遇到各种问题。这里总结几个典型场景。依赖冲突解决./gradlew dependencies deps.txt分析依赖树排除冲突版本端口占用处理# Mac/Linux lsof -i :8090 kill -9 PID # Windows netstat -ano | findstr 8090 taskkill /F /PID PIDGradle构建缓存清理./gradlew clean rm -rf ~/.gradle/caches/UI资源加载失败 检查是否同时运行了UI服务以及代理配置是否正确经过这些步骤你应该已经建立了一个完整的Halo开发环境。记得定期执行git pull获取最新代码并关注GitHub仓库的issue区获取最新动态。开发过程中遇到问题时先检查日志文件大多数情况下错误信息会给出明确提示。
Halo 2.11+开发环境搭建全攻略：从零配置到联调（含跨域避坑）
发布时间：2026/5/19 23:17:52
Halo 2.11开发环境搭建实战手册从环境配置到联调优化第一次接触Halo开源项目时我被它优雅的设计理念所吸引——一个现代化的Java博客系统却融合了前后端分离架构的灵活性和单体应用的部署便利性。但真正开始搭建开发环境时才发现要同时运行主项目和UI服务并非想象中那么简单特别是跨域问题这个隐形杀手让不少开发者栽了跟头。本文将带你从零开始用最接地气的方式完成整个开发环境的搭建。1. 开发环境准备构建稳固基石在开始Halo开发之旅前我们需要确保本地环境满足基本要求。不同于简单的运行环境开发环境需要更精细的版本控制。核心组件清单OpenJDK 17 LTSHalo 2.11基于Spring Boot 3.x构建必须使用JDK 17Node.js 20 LTSUI部分采用现代前端技术栈pnpm 9比npm/yarn更高效的依赖管理工具Git代码版本控制必备IntelliJ IDEA推荐使用2023.1版本对Gradle支持更完善提示环境变量配置是新手常忽略的点特别是JAVA_HOME和PATH的设置。验证Java环境是否正确java -version javac -version版本兼容性矩阵组件最低版本推荐版本备注JDK17.0.217.0.8长期支持版Node18.12.020.9.0偶数版更稳定pnpm8.6.09.0.5必须≥8.0安装完成后建议执行以下命令验证环境node -v pnpm -v git --version2. 项目初始化从克隆到结构解析Halo项目采用多模块设计理解项目结构对后续开发至关重要。不同于简单克隆就能运行的项目Halo需要同时管理主项目和UI子项目。克隆项目的最佳实践# 使用SSH方式克隆推荐开发者 git clone gitgithub.com:halo-dev/halo.git cd halo项目目录结构深度解析halo ├── application # 主模块Spring Boot入口 ├── common # 公共模块 ├── framework # 框架核心 ├── infra # 基础设施 ├── plugins # 插件系统 └── ui # 前端项目ConsoleUC特别需要注意的是从2.11版本开始UI目录同时包含Console管理后台运行在3000端口UC用户中心运行在4000端口注意开发环境下UI资源不会自动构建到主项目这与生产环境不同必须同时运行两个服务。3. UI服务启动现代前端工具链实战进入ui目录你会看到一个典型的现代前端项目。Halo采用Vite 4构建相比Webpack有着更快的启动速度。启动UI服务的完整流程cd ui pnpm install # 安装依赖首次需要 pnpm build:packages # 构建基础包 pnpm dev # 启动开发服务器成功启动后控制台会显示VITE v4.2.3 ready in 638 ms ➜ Console: http://localhost:3000/console/ ➜ UC: http://localhost:4000/uc/常见问题排查依赖安装失败尝试删除node_modules和pnpm-lock.yaml后重新安装端口冲突修改vite.config.ts中的端口配置内存不足Node.js默认内存限制可能不够可设置NODE_OPTIONS--max-old-space-size40964. 主项目启动Spring Boot深度配置回到项目根目录我们需要配置IntelliJ IDEA来启动主项目。这里有几个关键点需要注意。Gradle初始配置打开IntelliJ IDEA选择Open导入项目等待Gradle自动初始化和依赖下载完成确保使用Gradle Wrapper推荐运行配置详解Windows用户Active Profiles设置为dev,win需要额外处理路径分隔符问题Mac/Linux用户Active Profiles只需设置为dev内存参数建议-Xmx1024m命令行启动方案# Mac/Linux ./gradlew bootRun --args--spring.profiles.activedev # Windows gradlew.bat bootRun --args--spring.profiles.activedev,win成功启动后控制台会输出Started Application in 5.302 seconds5. 跨域问题终极解决方案这是大多数开发者遇到的第一个真正的挑战。由于UI服务运行在3000/4000端口而主API在8090端口浏览器会阻止这种跨域请求。Halo的代理配置原理 主项目的application-dev.yml中已经预设了代理规则halo: console: proxy: endpoint: http://localhost:3000/ enabled: true uc: proxy: endpoint: http://localhost:4000/ enabled: true正确访问方式管理后台http://localhost:8090/console用户中心http://localhost:8090/uc主站APIhttp://localhost:8090/api调试技巧使用浏览器开发者工具检查Network请求确认请求是否被正确代理检查响应头是否包含Access-Control-Allow-Origin6. 开发模式下的高效工作流建立了完整环境后如何高效开发是关键。Halo的多模块设计需要特定的工作流程。热重载配置前端Vite默认支持热更新后端Spring DevTools需要额外配置// build.gradle developmentOnly org.springframework.boot:spring-boot-devtools联调最佳实践先启动UI服务pnpm dev再启动主项目修改前端代码即时生效后端修改需要重启配置LiveReload可减少重启次数日志查看技巧tail -f ~/halo-next/logs/spring.log7. 进阶配置与性能调优当基础环境运行稳定后可以考虑进一步的优化配置。JVM参数调整 在IDEA的Run Configuration中添加-XX:UseG1GC -Xms512m -Xmx1024m -XX:MaxRAMPercentage75数据库切换 开发环境默认使用H2但可以改为MySQLspring: datasource: url: jdbc:mysql://localhost:3306/halo_dev username: root password: yourpassword缓存配置spring: cache: type: redis redis: host: localhost port: 63798. 常见问题与快速排错即使按照步骤操作仍可能遇到各种问题。这里总结几个典型场景。依赖冲突解决./gradlew dependencies deps.txt分析依赖树排除冲突版本端口占用处理# Mac/Linux lsof -i :8090 kill -9 PID # Windows netstat -ano | findstr 8090 taskkill /F /PID PIDGradle构建缓存清理./gradlew clean rm -rf ~/.gradle/caches/UI资源加载失败 检查是否同时运行了UI服务以及代理配置是否正确经过这些步骤你应该已经建立了一个完整的Halo开发环境。记得定期执行git pull获取最新代码并关注GitHub仓库的issue区获取最新动态。开发过程中遇到问题时先检查日志文件大多数情况下错误信息会给出明确提示。
