JHipster应用部署Koyeb时Java/JVM Buildpack未自动检测问题排查

背景 #

用JHipster生成了Spring Boot + React基础应用，本地环境Node版本v20.15.0、Java版本21，运行./mvnw可正常启动并连接数据库，但部署到Koyeb时失败。Koyeb底层采用Heroku的Buildpack检测机制，因此归为Heroku相关问题。

现有配置 #

• Procfile：

web: java $JAVA_OPTS -Xmx256m -jar build/libs/*.jar --spring.profiles.active=prod,koyeb

• application-koyeb.yml：

eureka:
  instance:
    hostname: formatted-for-post.koyeb.app
    non-secure-port: 8080
    prefer-ip-address: false

spring:
  datasource:
    type: com.zaxxer.hikari.HikariDataSource
    url: ${JDBC_DATABASE_URL}
    username: ${JDBC_DATABASE_USERNAME}
    password: ${JDBC_DATABASE_PASSWORD}
    hikari:
      maximumPoolSize: 8
server:
  port: ${PORT:8080}

尝试操作及报错 #

• 未添加构建后命令：部署阶段提示java command is not found
• 添加构建后命令chmod +x ./mvnw && ./mvnw -Pprod clean verify：构建阶段提示The JAVA_HOME environment variable is not defined correctly, this environment variable is needed to run this program.

额外信息 #

根目录已存在pom.xml、system.properties、mvnw文件，但Buildpack检测器未识别Java环境。本地执行pack build -B koyeb/builder formatted时，检测阶段无报错但卡住。

问题 #

为什么Java/JVM Buildpack未被自动识别？该如何排查具体故障原因？

排查与解决步骤 #

1. 校验system.properties的Java版本配置 #

确保system.properties中明确指定Java版本，JVM Buildpack依赖该文件识别版本：

java.runtime.version=21

版本号需与本地一致，且属于Buildpack支持的范围。

2. 确认Buildpack检测触发条件 #

Heroku JVM Buildpack会检测根目录下的pom.xml、build.gradle或system.properties文件。若pom.xml不在仓库根路径（比如JHipster项目将Java代码放在子目录），Buildpack会检测失败。检查项目结构，保证pom.xml位于代码仓库根目录。

3. 手动指定Buildpack #

若自动检测失效，在Koyeb部署配置中手动添加Buildpack：

• 先添加Node.js Buildpack（用于构建React前端）：https://github.com/heroku/heroku-buildpack-nodejs.git
• 再添加JVM Buildpack（用于构建Spring Boot后端）：https://github.com/heroku/heroku-buildpack-jvm.git
  注意Buildpack顺序必须先前端后后端，否则会导致构建流程出错。

4. 检查mvnw的权限与兼容性 #

• 确保mvnw在Git仓库中处于可执行状态：本地执行chmod +x mvnw后提交代码
• 更新mvnw至支持Java 21的版本（建议Maven 3.9及以上），避免版本不兼容问题

5. 查看Koyeb构建日志详情 #

部署失败后，查看完整的构建日志，重点关注Buildpack检测阶段的输出，日志会明确提示未选择JVM Buildpack的原因，比如“未检测到Java相关文件”或“版本不支持”。

6. 本地用Pack CLI排查 #

本地执行pack build时添加--verbose参数，查看详细日志定位问题：

pack build -B koyeb/builder formatted --verbose

从日志中确认检测阶段是否识别到Java项目，以及构建过程中具体卡住的环节。

内容的提问来源于stack exchange，提问作者Eric