Quarkus+GraalVM构建原生镜像部署AWS Lambda报AWT运行异常

使用Quarkus搭配GraalVM构建native image，上传部署至AWS Lambda运行时，调用PDFBox执行PDF渲染生成图片操作时抛出如下异常：

java.lang.UnsupportedOperationException: Add AWT Quarkus extension to enable Java2D/ImageIO. Additional system libraries such as `freetype' and `fontconfig' might be needed.
at java.awt.GraphicsEnvironment.getLocalGraphicsEnvironment(GraphicsEnvironment.java:45)
at java.awt.image.BufferedImage.createGraphics(BufferedImage.java:1181)
at org.apache.pdfbox.rendering.PDFRenderer.renderImage(PDFRenderer.java:335)
at org.apache.pdfbox.rendering.PDFRenderer.renderImage(PDFRenderer.java:272)
at org.apache.pdfbox.rendering.PDFRenderer.renderImage(PDFRenderer.java:232)
at org.apache.pdfbox.rendering.PDFRenderer.renderImage(PDFRenderer.java:219)
at com.smartproof.lambda.service.CertificateGeneratorService.addOpenBadgeMetadata(CertificateGeneratorService.java:235)
at com.smartproof.lambda.service.CertificateGeneratorService.generateCertificate(CertificateGeneratorService.java:103)
at com.smartproof.lambda.service.CertificateGeneratorService_ClientProxy.generateCertificate(Unknown Source)
at com.smartproof.lambda.CertificateGeneratorLambda.handleRequest(CertificateGeneratorLambda.java:26)
at com.smartproof.lambda.CertificateGeneratorLambda.handleRequest(CertificateGeneratorLambda.java:17)
at io.quarkus.amazon.lambda.runtime.AmazonLambdaRecorder$1.processRequest(AmazonLambdaRecorder.java:170)
at io.quarkus.amazon.lambda.runtime.AbstractLambdaPollLoop$1.run(AbstractLambdaPollLoop.java:130)
at java.lang.Thread.run(Thread.java:829)
at com.oracle.svm.core.thread.JavaThreads.threadStartRoutine(JavaThreads.java:597)
at com.oracle.svm.core.posix.thread.PosixJavaThreads.pthreadStartRoutine(PosixJavaThreads.java:194)

异常提示需添加AWT Quarkus扩展以启用Java2D/ImageIO，运行环境可能还需要安装freetype、fontconfig等系统依赖，触发点为PDFBox的图片渲染逻辑。

• GraalVM native image构建默认不会包含Java AWT/Java2D/ImageIO相关类与原生依赖元数据，Quarkus将AWT能力作为可选扩展隔离，未引入对应扩展时调用图形API会直接抛出不支持操作异常
• AWT图形渲染、字体处理逻辑依赖freetype、fontconfig等系统级原生库，AWS Lambda默认运行时环境未预装这些依赖，仅引入代码层扩展仍会因缺系统库运行失败
• PDFBox的PDF转图片逻辑底层直接依赖BufferedImage、Graphics2D等Java2D API，会直接触发AWT能力的可用性校验

• 第一步：引入Quarkus AWT扩展
  根据项目构建工具执行对应命令，引入后Quarkus构建native image时会自动打包AWT/ImageIO相关的GraalVM元数据、Java2D依赖类：

  # Maven项目
  ./mvnw quarkus:add-extension -Dextensions="awt"
  
  # Gradle项目
  ./gradlew addExtension --extensions="awt"
  

• 第二步：解决Lambda运行时系统依赖缺失问题
  两种方案二选一即可：
  1. 使用Lambda Layer打包freetype、fontconfig运行时库，挂载到目标Lambda函数后，配置环境变量LD_LIBRARY_PATH指向层内库路径
  2. 构建native image时开启静态编译，将依赖的系统库直接打包进native产物，在application.properties中添加配置：

     quarkus.native.additional-build-args=--static
     

     注意静态编译需要提前在native构建环境（即执行native构建的机器，不是Lambda运行环境；如果使用容器构建native，需要在构建阶段的镜像中安装依赖）安装freetype-devel、fontconfig-devel依赖包，否则构建阶段会报错。
• 第三步：补充PDFBox相关native配置
  若引入扩展、补全系统库后仍报类找不到、资源缺失错误，是因为PDFBox内部存在大量反射调用、字体资源加载逻辑，GraalVM静态分析时无法自动识别，需要在src/main/resources目录下添加GraalVM native配置文件，将PDFBox用到的反射类、字体资源路径加入构建清单；如果存在适配Quarkus的PDFBox扩展，直接引入扩展可自动完成该配置。
• 第四步：本地验证后再部署
  本地执行./mvnw clean install -Dnative（Maven）或对应Gradle命令构建native产物，使用和AWS Lambda一致的Amazon Linux 2环境本地运行验证PDF渲染逻辑正常后，再上传部署到云端，降低云端调试成本。

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