Docker镜像中传递--add-opens JVM参数失败问题排查

我有一个运行Spring Boot服务的Docker镜像，需要传递--add-opens JVM参数，但启动时报错。相关配置如下：

Dockerfile内容 #

FROM amazoncorretto:21.0.4

ENV JAVA_TOOL_OPTIONS="-Xms2g -Xmx8g -XX:MaxMetaspaceSize=512M -XX:+UseG1GC --add-opens java.base/java.lang=ALL-UNNAMED"

# Add the JAR file to the container
ADD target/evaluation-service.jar evaluation-service.jar

# Define the entry point
ENTRYPOINT ["java", "-jar", "evaluation-service.jar"]

镜像启动命令 #

docker run --platform linux/arm64 -d --expose 8302 -p 8302:8302 --memory=8g  --name evaluation  285bc34ead55   --server.port=8302 

启动错误信息 #

Picked up JAVA_TOOL_OPTIONS: -Xms2g -Xmx8g -XX:MaxMetaspaceSize=512M -XX:+UseG1GC --add-opens java.base/java.lang=ALL-UNNAMED
Unrecognized option: --add-opens
Error: Could not create the Java Virtual Machine.
Error: A fatal exception has occurred. Program will exit

移除--add-opens java.base/java.lang=ALL-UNNAMED参数后镜像可正常启动，请问哪里操作有误？

问题原因及解决方法 #

核心问题 #

--add-opens是Java 9+引入的模块化JVM选项，通过JAVA_TOOL_OPTIONS传递时，部分JVM环境会出现解析异常，导致参数不被识别。直接将这类参数写入ENTRYPOINT的命令序列中是更可靠的方式。

解决步骤 #

1. 修改Dockerfile，整合JVM参数到ENTRYPOINT
   将所有JVM参数（包括--add-opens）直接加入ENTRYPOINT的JVM命令里，替换原有的JAVA_TOOL_OPTIONS配置：

   FROM amazoncorretto:21.0.4
   
   # Add the JAR file to the container
   ADD target/evaluation-service.jar evaluation-service.jar
   
   # 直接在ENTRYPOINT中定义所有JVM选项
   ENTRYPOINT ["java", "--add-opens", "java.base/java.lang=ALL-UNNAMED", "-Xms2g", "-Xmx8g", "-XX:MaxMetaspaceSize=512M", "-XX:+UseG1GC", "-jar", "evaluation-service.jar"]
   

2. 重新构建镜像

   docker build -t evaluation-service .
   

3. 启动镜像
   注意--server.port=8302是Spring Boot应用参数，需放在镜像名/ID之后：

   docker run --platform linux/arm64 -d -p 8302:8302 --memory=8g --name evaluation evaluation-service --server.port=8302
   

备选方案（保留JAVA_TOOL_OPTIONS） #

如果坚持使用JAVA_TOOL_OPTIONS，可以尝试将--add-opens改为等号连接的格式，部分JVM对这种格式的解析更稳定：

ENV JAVA_TOOL_OPTIONS="-Xms2g -Xmx8g -XX:MaxMetaspaceSize=512M -XX:+UseG1GC --add-opens=java.base/java.lang=ALL-UNNAMED"

额外优化 #

启动命令中的--expose 8302可以移除，因为-p 8302:8302已经包含了端口暴露的功能。

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