升级AWS CDK至1.152.0时如何修复setContext报错问题

核心问题解析 #

1. setContext报错原因：CDK 1.x后期版本强化了上下文生命周期管理，App实例初始化后内部节点树已构建完成，此时调用app.node.setContext会触发Cannot set context after children have been added: Tree错误，必须在创建App时一次性传入所有上下文数据。
2. 环境变量undefined原因：Node.js默认不会自动加载.env文件，且CDK执行时不会自动将终端环境变量注入到Node进程（除非显式传入）。

解决方案一：使用环境变量 + dotenv（推荐CI/CD场景） #

步骤1：安装dotenv依赖 #

npm install dotenv --save-dev

步骤2：重构代码 #

import * as cdk from 'aws-cdk-lib';
import dotenv from 'dotenv';

// 加载.env文件中的环境变量（本地开发用）
dotenv.config();

// 提前构建配置，避免依赖App实例的context
const stage = process.env.STAGE || 'dev';
const targetStage = ['prod', 'test'].includes(stage) ? stage : 'dev';

// 解析stageConfig（如果环境变量是JSON字符串，需用JSON.parse转换）
const stageConfig = process.env[targetStage.toUpperCase()] 
  ? JSON.parse(process.env[targetStage.toUpperCase()]) 
  : {};

const appConfig: AppConfig = {
  domainName: process.env.DOMAINNAME || 'default.example.com', // 可设置默认值避免空值
  isProduction: stage === 'prod',
  stageName: stage,
  stageConfig
};

// 创建App时直接传入所有上下文
const app = new cdk.App({
  context: {
    config: appConfig,
    // 保留原有的上下文参数，兼容下游代码逻辑
    stage: stage,
    domainName: appConfig.domainName,
    [targetStage]: stageConfig
  }
});

// 后续创建你的业务Stack
// new YourBusinessStack(app, 'YourBusinessStack', {
//   env: { account: process.env.CDK_DEFAULT_ACCOUNT, region: process.env.CDK_DEFAULT_REGION }
// });

步骤3：传入环境变量 #

• 本地开发：在项目根目录创建.env文件：

  STAGE=dev
  DOMAINNAME=dev.example.com
  DEV={"apiUrl": "https://dev-api.example.com"}
  PROD={"apiUrl": "https://api.example.com"}
  

• 终端执行命令：

  # Unix/Linux
  STAGE=prod DOMAINNAME=prod.example.com PROD='{"apiUrl":"https://api.example.com"}' cdk deploy
  
  # Windows
  set STAGE=prod && set DOMAINNAME=prod.example.com && set PROD={"apiUrl":"https://api.example.com"} && cdk deploy
  

解决方案二：继续使用CDK命令行context参数（兼容原有工作流） #

如果习惯用cdk deploy -c stage=prod的方式传参，可通过解析命令行参数提前构建配置，避免依赖App实例的tryGetContext：

import * as cdk from 'aws-cdk-lib';

// 解析命令行传入的-c参数
const context: Record<string, string> = {};
process.argv.slice(2)
  .filter(arg => arg.startsWith('-c'))
  .forEach(arg => {
    const [key, value] = arg.slice(2).split('=');
    context[key] = value;
  });

// 构建配置
const stage = context.stage || 'dev';
const domainName = context.domainName || 'default.example.com';
const targetStage = ['prod', 'test'].includes(stage) ? stage : 'dev';
const stageConfig = context[targetStage] ? JSON.parse(context[targetStage]) : {};

const appConfig: AppConfig = {
  domainName,
  isProduction: stage === 'prod',
  stageName: stage,
  stageConfig
};

// 创建App时传入完整上下文
const app = new cdk.App({
  context: {
    ...context, // 保留原命令行传入的所有context
    config: appConfig // 注入组装好的全局配置
  }
});

// 后续创建业务Stack
// new YourBusinessStack(app, 'YourBusinessStack', { ... });

使用方式 #

cdk deploy -c stage=prod -c domainName=prod.example.com -c prod='{"apiUrl":"https://api.example.com"}'

关键注意事项 #

• 所有上下文数据必须在new cdk.App()时传入，禁止在App创建后调用setContext。
• 如果需要传递复杂类型的上下文（如对象），需将其序列化为JSON字符串，再用JSON.parse解析。
• 确保CDK命令执行时，环境变量或命令行参数已正确传入，避免出现undefined。

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