CDK Pipelines结合CodePipeline无法部署大型CloudFormation模板

问题背景 #

使用AWS CodePipeline或CDK Pipeline部署CloudFormation资产时，Assets阶段抛出以下错误：

Template format error: JSON not well-formed. (line 1135, column 4) (Service: AmazonCloudFormation; Status Code: 400; Error Code: ValidationError; Request ID: XXXXXXXX; Proxy: null)

本地通过cdk deploy可正常部署，说明模板本身无语法问题。该问题多发生在模板体积过大时，拆分多栈可临时缓解，但AppSync API等场景下拆分栈并不现实。

可行解决方案 #

1. 开启CDK模板分块功能 #

CDK支持将大模板自动分块，避免CodePipeline处理时出现JSON截断。在Pipeline的Synth步骤中添加参数：

new CodePipeline(this, 'MyPipeline', {
  synth: new ShellStep('Synth', {
    input: CodePipelineSource.gitHub('your/repo', 'main'),
    commands: [
      'npm ci',
      'npm run build',
      'npx cdk synth --template-chunk-size 5000' // 调整分块大小（单位：字节）
    ],
  }),
});

默认分块大小为10000字节，根据模板实际体积调小参数值，可解决JSON格式异常问题。

2. 自定义资产部署Lambda步骤 #

绕过CodePipeline默认的Assets部署流程，改用Lambda函数手动处理模板部署：

• 编写Lambda函数，从S3读取合成后的CloudFormation模板，调用CreateStack/UpdateStack API完成部署
• 在Pipeline中添加InvokeLambdaAction，替换原有的Assets阶段动作
  这种方式可规避CodePipeline内部处理大模板时的格式转换bug。

3. 升级CDK至最新稳定版 #

部分旧版本CDK存在大模板资产打包的已知缺陷，升级到2.x系列的最新稳定版，AWS官方可能已修复相关Pipeline兼容性问题。

4. 优化模板体积（无需拆分栈） #

通过以下方式减小模板体积，从根源降低触发bug的概率：

• 复用重复资源：使用CfnInclude或嵌套栈共享通用配置
• 移除冗余内容：删除模板中不必要的注释、空字段
• 外置大字符串：将AppSync resolver代码、大配置文本等存储到S3，通过Fn::GetAtt或Fn::ImportValue引用，避免直接嵌入模板

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