AWS CDK构建Docker镜像Lambda函数时触发运行时错误排查

问题场景 #

使用AWS CDK通过Docker镜像构建Java实现的Lambda函数，镜像构建成功，但创建Lambda函数时触发错误，即使已明确指定Runtime.FROM_IMAGE。后续改用TypeScript实现相同栈，仍出现完全相同的错误。

Java实现代码 #

// 构建Docker镜像
AssetCode code = Code.fromDockerBuild(file.toAbsolutePath().toString(),
        DockerBuildAssetOptions.builder()
             .imagePath("/var/task")
             .outputPath(file.toAbsolutePath().toString() + "/cdk.out" )
             .platform("linux/amd64")
             .build()
   );

// 创建Lambda函数
Function lambda = Function.Builder.create(stack, LAMBDA_FUNCTION_ID)
          .runtime(Runtime.FROM_IMAGE)
          .description("My Description ")
          .role(lambdaRole)
          .code(code)
          .handler("com.mycompany.myproject.MyHandler")
          .memorySize(1024)
          .environment(env)
          .logRetention(ONE_WEEK)
          .timeout(Duration.seconds(60))
          .events(List.of(source))
          .build();

触发的错误信息 #

Exception in thread "main" software.amazon.jsii.JsiiError: runtime must be 'Runtime.FROM_IMAGE' when using image asset for Lambda function Error: runtime must be 'Runtime.FROM_IMAGE' when using image asset for Lambda function

疑问 #

1. 原Function创建方法是否正确？
2. 这是否是已知问题？未在官方问题日志中找到相关线索。

更新：TypeScript实现同样报错 #

TypeScript代码 #

const code = Code.fromDockerBuild(path,  {imagePath: '/var/task', outputPath: path})

const lambda = new Function(this, this.getVariable('LAMBDA_FUNCTION_ID', fdEnv),  {
      code: code,
      handler: "com.mycompany.myproject.MyHandler",
      runtime: Runtime.FROM_IMAGE,
      description: '',
      role: lambdaRole,
      memorySize: 1024,
      environment: fdEnv.value,
      logRetention: RetentionDays.ONE_WEEK,
      timeout: Duration.seconds(60),
      events: [eventSource]
    })

错误信息 #

Error: runtime must be `Runtime.FROM_IMAGE` when using image asset for Lambda function

排查与解决方法 #

1. 核心问题：Code类型使用错误 #

原代码中使用的Code.fromDockerBuild属于普通AssetCode范畴，是为zip格式的Lambda部署包设计的，与镜像部署不兼容。正确的做法是使用**DockerImageCode**来处理Docker镜像资产。

2. 修正后的代码示例 #

Java版本

// 替换AssetCode为DockerImageCode
DockerImageCode code = DockerImageCode.fromDockerBuild(file.toAbsolutePath().toString(),
    DockerImageAssetOptions.builder()
        .platform("linux/amd64")
        .build()
);

// 推荐使用DockerImageFunction（无需手动指定Runtime.FROM_IMAGE）
DockerImageFunction lambda = DockerImageFunction.Builder.create(stack, LAMBDA_FUNCTION_ID)
    .code(code)
    .handler("com.mycompany.myproject.MyHandler")
    .role(lambdaRole)
    .memorySize(1024)
    .environment(env)
    .logRetention(ONE_WEEK)
    .timeout(Duration.seconds(60))
    .events(List.of(source))
    .build();

// 或继续使用Function构造器（需保留Runtime.FROM_IMAGE）
// Function lambda = Function.Builder.create(stack, LAMBDA_FUNCTION_ID)
//     .runtime(Runtime.FROM_IMAGE)
//     .code(code)
//     .handler("com.mycompany.myproject.MyHandler")
//     .role(lambdaRole)
//     .memorySize(1024)
//     .environment(env)
//     .logRetention(ONE_WEEK)
//     .timeout(Duration.seconds(60))
//     .events(List.of(source))
//     .build();

TypeScript版本

// 替换Code.fromDockerBuild为DockerImageCode.fromDockerBuild
const code = DockerImageCode.fromDockerBuild(path, {
  platform: 'linux/amd64'
});

// 推荐使用DockerImageFunction
const lambda = new DockerImageFunction(this, this.getVariable('LAMBDA_FUNCTION_ID', fdEnv), {
  code: code,
  handler: "com.mycompany.myproject.MyHandler",
  role: lambdaRole,
  memorySize: 1024,
  environment: fdEnv.value,
  logRetention: RetentionDays.ONE_WEEK,
  timeout: Duration.seconds(60),
  events: [eventSource]
});

3. 额外排查步骤 #

• 升级CDK版本：运行cdk --version检查版本，若低于2.80.0建议升级到最新稳定版，早期版本可能存在JSII对Runtime.FROM_IMAGE的序列化问题。
• 清理CDK缓存：删除cdk.out目录后重新执行cdk synth，避免缓存的旧配置干扰。
• 验证Dockerfile规范：确保Dockerfile符合Lambda镜像要求，比如工作目录设为/var/task，包含正确的运行时启动逻辑。

疑问解答 #

1. 原Function创建方法不正确：错误使用了针对zip包的AssetCode处理镜像资产，导致CDK无法识别镜像部署类型。
2. 这不属于普遍已知问题，主要是API使用不当或版本兼容性问题，修正Code类型并升级CDK版本后即可解决。

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