CDK结合SAM本地开发如何正确配置本地环境变量

问题场景 #

• 现有工作流：
  • 本地测试：执行 cdk synth --no-staging > template.yaml && sam local start-api 生成模板并启动本地API
  • 线上部署：执行 cdk deploy testStack123 --context secretToken=123 通过CDK上下文传入敏感参数
• 核心矛盾：
  纯SAM项目可通过加入.gitignore的env.json传入本地敏感环境变量，部署时通过命令参数传值即可实现环境隔离，但CDK合成的CloudFormation模板会为自定义Lambda资源自动追加哈希后缀（例如代码中定义的TestLambdaFunction，模板中实际逻辑ID为TestLambdaFunction67CA3BED），导致env.json中手动填写的Lambda ID无法匹配，本地变量注入失败。
• 已验证不可行的方案：
  • 直接执行 sam local start-api --env-vars env.json：因上述逻辑ID哈希后缀问题，变量无法匹配到对应Lambda
  • 将敏感值写入cdk.json通过CDK上下文传入：cdk.json需要提交到代码仓库，存在敏感信息意外提交的泄露风险

推荐落地方案 #

方案1（最简便，推荐优先使用）：CDK层做环境判断，合成阶段直接注入本地变量 #

直接在CDK代码中增加环境分支判断，不需要依赖SAM的--env-vars参数，从根源上避开逻辑ID匹配问题：

1. 将本地敏感配置存放在加入.gitignore的env.json文件中，不提交到仓库
2. 在CDK代码中增加本地环境判断：本地synth场景下读取env.json的配置值，部署场景下读取CDK上下文传入的参数值，统一注入到Lambda的环境变量配置中
   以TypeScript版本CDK为例，核心实现代码如下：

import * as fs from 'fs';
import * as path from 'path';

// 通过自定义环境变量标记本地synth场景
const isLocalEnv = process.env.CDK_LOCAL === '1';
const localEnvConfig = isLocalEnv 
  ? JSON.parse(fs.readFileSync(path.resolve(__dirname, '../env.json'), 'utf8'))
  : {};

// 定义Lambda资源时统一注入环境变量
const demoLambda = new lambda.Function(this, 'TestLambdaFunction', {
  runtime: lambda.Runtime.NODEJS_18_X,
  handler: 'index.handler',
  code: lambda.Code.fromAsset('src/lambda/demo'),
  environment: {
    SECRET_TOKEN: isLocalEnv ? localEnvConfig.SECRET_TOKEN : this.node.getContext('secretToken'),
    ENVIRONMENT: isLocalEnv ? 'local' : 'test'
  }
});

3. 调整本地测试命令，synth前先注入本地标记变量：

CDK_LOCAL=1 cdk synth --no-staging > template.yaml && sam local start-api

该方案下SAM启动时会直接读取模板中已经注入好的本地环境变量，不需要额外传参，也完全不需要关心CDK生成的逻辑ID后缀问题，配置隔离符合安全要求。

方案2（无CDK代码侵入）：synth后自动生成匹配ID的环境变量文件 #

如果不想修改现有CDK逻辑，可以写一个轻量预处理脚本，在CDK合成模板后自动匹配Lambda的实际逻辑ID，生成SAM可识别的环境变量文件：

1. 脚本核心逻辑：
   • 读取cdk synth生成的template.yaml，遍历Resources段筛选所有类型为AWS::Lambda::Function的资源，记录其完整逻辑ID
   • 基于前缀匹配规则，将本地env.json中手动填写的无后缀Lambda ID，映射到模板中带哈希后缀的实际ID
   • 生成临时的env.generated.json文件，同样加入.gitignore
2. 调整本地测试命令为链式执行：

cdk synth --no-staging > template.yaml && node scripts/generate-local-env.js && sam local start-api --env-vars env.generated.json

该方案不需要改动CDK业务代码，仅需维护一个几十行的预处理脚本即可，匹配逻辑稳定可靠——CDK生成的逻辑ID固定为「用户定义ID+8位哈希后缀」格式，前缀匹配不会出现误匹配问题。

方案3（长期规范方案）：统一从密钥管理服务拉取配置 #

如果团队已经在用AWS Secrets Manager、Parameter Store这类配置/密钥管理服务，可以直接让Lambda运行时从对应服务拉取敏感配置，本地开发时通过本地AWS凭证读取测试环境的专属参数值，不需要在本地文件存储敏感令牌，也不需要区分本地和部署环境的变量注入逻辑。

注意：需要严格做权限隔离，给本地开发使用的IAM角色仅分配测试环境密钥的读取权限，禁止访问生产环境配置。

内容的提问来源于stack exchange，提问作者Adam E.