如何解决CDK自变更CodePipeline部署React应用的构建队列限制问题

问题根源 #

你的错误是因为AWS CodeBuild账户默认排队构建数限制为1，而CDK在部署BucketDeployment这类资源时，会自动启动额外的CodeBuild任务处理本地资产（也就是你的React dist文件夹）。当Pipeline的构建任务和CDK自动创建的资产构建任务同时触发时，就会超出队列限制导致失败。哪怕你把前端构建和CDK Synth合并，CDK在部署阶段还是会启动独立的资产构建任务，所以问题依旧存在。

具体解决方法 #

1. 限制CDK资产构建的并发数（最快见效） #

通过CDK上下文参数@aws-cdk/core:assetParallelism强制CDK串行处理资产构建，避免同时触发多个CodeBuild任务。修改你的Launcher.ts：

import { App } from "aws-cdk-lib";
import { WebAppPipelineStack } from "./stacks/WebAppPipelineStack";

const app = new App({
  context: {
    // 限制资产构建并发数为1，避免超过队列限制
    "@aws-cdk/core:assetParallelism": 1
  }
});

new WebAppPipelineStack(app, "WebAppPipelineStack");

app.synth();

这个参数会让CDK逐个处理所有需要构建的资产，不会同时发起多个CodeBuild任务，从根本上避免队列溢出。

2. 预上传资产到S3，跳过CDK自动构建 #

把React构建产物提前上传到S3，在WebAppStack里直接引用S3上的资产，这样CDK就不会再自动创建CodeBuild任务。

步骤1：在Pipeline中添加上传dist到S3的步骤

修改WebAppPipelineStack.ts的Synth步骤，在构建完React后把dist文件夹上传到S3：

import * as s3 from "aws-cdk-lib/aws-s3";
import * as iam from "aws-cdk-lib/aws-iam";

// ... 其余导入代码不变

export class WebAppPipelineStack extends cdk.Stack {
  constructor(scope: Construct, id: string, props?: cdk.StackProps) {
    super(scope, id, props);

    // 创建存储预构建资产的S3桶
    const assetBucket = new s3.Bucket(this, "PrebuiltAssetBucket", {
      removalPolicy: cdk.RemovalPolicy.DESTROY,
      autoDeleteObjects: true
    });

    const pipeline = new CodePipeline(this, "WebAppPipeline", {
      pipelineName: "ServerlessPrototypeWebAppPipeline",
      synth: new ShellStep("Synth", {
        input: CodePipelineSource.gitHub("me/my-repo", "main"),
        commands: [
          // 构建React应用
          "cd packages/web/react-vite",
          "npm ci",
          "npm run build",
          // 上传dist到预构建资产桶
          `aws s3 sync dist s3://${assetBucket.bucketName}/web-app-dist`,
          // CDK Synth
          "cd ../../../packages/infra",
          "npm install -g esbuild ts-node",
          "npm ci",
          "npx cdk synth"
        ],
        primaryOutputDirectory: "packages/infra/cdk.out",
        // 给ShellStep添加S3写入权限
        rolePolicyStatements: [
          new iam.PolicyStatement({
            actions: ["s3:PutObject", "s3:ListBucket"],
            resources: [`${assetBucket.bucketArn}`, `${assetBucket.bucketArn}/web-app-dist/*`]
          })
        ]
      })
    });

    // ... 其余代码不变
  }
}

步骤2：修改WebAppStack.ts引用S3资产

把原来的Source.asset换成Source.s3Object：

import * as s3 from "aws-cdk-lib/aws-s3";

// ... 其余导入代码不变

export class WebAppStack extends Stack {
  constructor(scope: Construct, id: string, props?: StackProps) {
    super(scope, id, props);

    const deploymentBucket = new Bucket(this, "WebAppWebBucket", {
      bucketName: "my-prototype-web"
    });

    // 引用预构建资产桶
    const assetBucket = s3.Bucket.fromBucketName(this, "PrebuiltAssetBucket", "PrebuiltAssetBucket");

    new BucketDeployment(this, "WebAppWebBucketDeployment", {
      destinationBucket: deploymentBucket,
      sources: [Source.s3Object(assetBucket, "web-app-dist")]
    });

    // 其余代码不变...
  }
}

3. 申请提高CodeBuild账户限制 #

如果你的业务需要同时运行多个构建任务，可以通过AWS控制台提交支持请求，提高账户的CodeBuild排队构建数限制。路径：AWS控制台 -> Support Center -> 创建案例 -> 服务限制提升 -> 选择CodeBuild，填写需要提高的限制值。不过这个方法需要AWS审核，可能需要几个工作日才能生效。

验证方法 #

修改后重新部署Pipeline，观察Pipeline执行时的CodeBuild任务，应该不会再出现队列超出限制的错误，无需重试即可完成部署。

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