AWS CDK部署Lambda Layer遇“上传文件需为非空Zip”错误排查

上下文 #

• 使用Code.fromAsset()创建Lambda Layer
• 在cdk synth前已安装依赖
  示例代码：

new lambda.LayerVersion(this, "ExampleLayer", {
  code: lambda.Code.fromAsset("path-to-layer"),
  compatibleRuntimes: [lambda.Runtime.NODEJS_18_X],
});

文件夹结构 #

layer-folder/
  runtime-folder/
    package.json
    dependencies/
      some-library/

已验证内容 #

• 生成的Zip文件非空
• Layer内包含依赖
• 依赖安装在synth前执行
• 资源路径指向正确目录

观察到的行为 #

• cdk synth执行成功
• 创建Lambda Layer时部署失败
• 解压产物可见预期文件

疑问 #

1. 哪些原因会导致AWS Lambda将有效Layer Zip判定为“空”？是否存在以下已知问题：
   • CDK资源打包/缓存问题？
   • 预期结构或必填文件缺失？
   • synth前依赖安装时机问题？
2. 若cdk.out内的资源路径在部署时未正确解析，是否会导致CDK抛出“非空Zip”错误？是否存在以下场景：synth与deploy之间资源路径失效，或CDK在非生成位置查找资源？求告知CDK在cdk deploy --app cdk.out时解析资源路径的机制。

一、导致Lambda判定Zip为空的常见原因 #

1. Layer结构不符合Lambda强制规范 #

Node.js Layer的依赖必须放在nodejs/node_modules目录下（Lambda会默认扫描该路径识别有效内容）。你的文件夹结构是runtime-folder/dependencies/，完全不符合要求——Lambda遍历Zip后找不到预期的依赖目录，会直接判定Layer为空。

2. CDK打包路径指向错误 #

如果path-to-layer指向的是runtime-folder而非layer-folder，打包后的Zip仅包含package.json和dependencies，没有符合要求的层级结构，Lambda无法识别有效内容。

3. CDK缓存或打包异常 #

• Code.fromAsset()会在synth时将资源打包到cdk.out，若之前的打包缓存未清理，可能复用旧的空Zip文件。
• 若synth前依赖安装脚本是异步执行（比如后台安装），可能出现synth触发时依赖还未生成，导致打包出空Zip（你已验证依赖在synth前完成，此场景概率较低）。

4. 权限缺失 #

部署时若CDK没有读取cdk.out内资产文件的权限，会导致上传内容为空，Lambda返回“非空Zip”错误。

二、cdk deploy --app cdk.out的路径解析机制 #

执行cdk synth时，CDK会完成以下操作：

1. 将Code.fromAsset()指向的本地资源打包成Zip，存入cdk.out的assets/目录。
2. 生成CloudFormation模板和asset-manifest.json资产清单，记录资产的本地绝对路径、目标S3位置等信息。

执行cdk deploy --app cdk.out时：

• CDK读取cdk.out内的资产清单，根据清单中的绝对路径找到对应的Zip文件。
• 将Zip上传到CDK预先创建的S3资产桶，再通过CloudFormation将S3路径关联到Lambda Layer资源。

路径失效的场景及影响 #

• synth与deploy之间移动cdk.out：资产清单中的路径是绝对路径，cdk.out被移动后，CDK找不到对应Zip，抛出ENOENT错误，此时上传到Lambda的内容为空，触发“非空Zip”报错。
• synth与deploy之间修改本地资源：cdk.out内的资产是synth时的快照，修改本地资源不会影响已生成的Zip，除非重新执行synth。
• CDK版本不一致：不同版本CDK的资产清单格式可能有差异，synth和deploy用不同版本会导致路径解析失败。

三、针对性解决方案 #

1. 调整Layer目录结构为Lambda要求的格式：

   layer-folder/
     nodejs/
       package.json
       node_modules/
         some-library/
   

   然后将Code.fromAsset()的路径指向layer-folder。
2. 清理CDK缓存：执行cdk clean后重新synth和deploy。
3. 确保依赖安装同步完成：在synth前添加同步脚本，比如cd layer-folder/nodejs && npm install。
4. 检查cdk.out目录权限，确保部署用户拥有读取权限。
5. 禁止在synth和deploy之间移动或修改cdk.out，若需移动则重新执行synth生成新的资产清单。

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