如何在Dockerfile中定义并传递参数给CMD运行Java应用？及报错排查

错误根因 #

你遇到的Could not find or load main class ${JDK_JAVA_OPTIONS}错误，是因为Docker的exec格式CMD（数组形式）不会执行shell变量替换——${JDK_JAVA_OPTIONS}被直接当作Java主类名传入，自然找不到对应的类。

修复方案 #

方案1：改用Shell格式CMD #

直接使用shell格式的CMD，让shell自动解析变量：

// some other command...

FROM ${REGISTRY}eclipse-temurin:17-jre-alpine
ARG JDK_JAVA_OPTIONS="${JAVA_OPTS} -Dcom.sun.management.jmxremote.port=1099 -Dcom.sun.management.jmxremote.ssl=false -Dcom.sun.management.jmxremote.authenticate=false --add-exports=java.base/sun.nio.ch=ALL-UNNAMED --add-opens=java.base/java.lang=ALL-UNNAMED --add-opens=java.base/java.lang.reflect=ALL-UNNAMED --add-opens=java.base/java.io=ALL-UNNAMED --add-exports=jdk.unsupported/sun.misc=ALL-UNNAMED"
COPY --from=builder /opt/my-app.jar /opt/my-app.jar
# 改用shell格式，自动解析变量
CMD java ${JDK_JAVA_OPTIONS} -jar /opt/my-app.jar

方案2：保留Exec格式但通过Shell代理 #

如果需要保留exec格式的特性，可以通过sh -c来启动命令，让shell处理变量替换：

CMD ["sh", "-c", "java ${JDK_JAVA_OPTIONS} -jar /opt/my-app.jar"]

关键补充：ARG转ENV #

注意：ARG是构建阶段变量，容器启动时默认不会保留。如果需要在容器运行时仍能访问该变量，需要将其转为ENV：

FROM ${REGISTRY}eclipse-temurin:17-jre-alpine
# 先声明JAVA_OPTS作为构建参数，默认值为空
ARG JAVA_OPTS=""
ARG JDK_JAVA_OPTIONS="${JAVA_OPTS} -Dcom.sun.management.jmxremote.port=1099 -Dcom.sun.management.jmxremote.ssl=false -Dcom.sun.management.jmxremote.authenticate=false --add-exports=java.base/sun.nio.ch=ALL-UNNAMED --add-opens=java.base/java.lang=ALL-UNNAMED --add-opens=java.base/java.lang.reflect=ALL-UNNAMED --add-opens=java.base/java.io=ALL-UNNAMED --add-exports=jdk.unsupported/sun.misc=ALL-UNNAMED"
# 将构建参数转为环境变量，容器启动时可访问
ENV JDK_JAVA_OPTIONS=${JDK_JAVA_OPTIONS}
COPY --from=builder /opt/my-app.jar /opt/my-app.jar
CMD java ${JDK_JAVA_OPTIONS} -jar /opt/my-app.jar

1. 构建时参数（ARG） #

• 用于镜像构建阶段，需在Dockerfile中用ARG声明，可通过docker build --arg KEY=VALUE或docker-compose的build.args传递。
• 若要在容器运行时使用构建参数，必须将其转为ENV（如上面的示例）。

2. 运行时环境变量（ENV） #

• 直接在Dockerfile中用ENV定义，容器启动时自动生效；也可通过docker run -e KEY=VALUE或docker-compose的environment覆盖。
• 适合需要在容器运行时动态调整的参数（如Java的堆内存配置）。

3. CMD的两种格式选择 #

• Shell格式：CMD command arg1 arg2，会启动shell解析变量，适合需要变量替换的场景（如Java启动命令）。
• Exec格式：CMD ["command", "arg1", "arg2"]，不会启动shell，变量不会被解析，适合不需要shell的场景；若要解析变量，需用["sh", "-c", "command ${VAR}"]包裹。

Docker-compose传递JAVA_OPTS示例 #

services:
  my-app:
    build:
      context: .
      args:
        REGISTRY: "your-registry-domain/"
        JAVA_OPTS: "-Xmx512m -Xms256m"

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