AWS StepFunctionsLocal测试时DefinitionSubstitutions未替换报错

核心问题 #

你遇到的是CloudFormation的DefinitionSubstitutions占位符（比如${StockCheckerFunctionArn}）仅在部署阶段由CloudFormation自动注入值，但本地用StepFunctionsLocal测试时，Makefile里的create-state-machine命令未做替换，导致SFL识别不了非法的ARN格式。

可行解决线索 #

• 脚本手动替换占位符：在调用aws stepfunctions create-state-machine前，用文本处理工具替换定义文件里的占位符。比如用sed（Linux/macOS）：

  # 示例：替换StockCheckerFunctionArn占位符为本地Lambda测试ARN
  sed -i.bak "s/\${StockCheckerFunctionArn}/arn:aws:lambda:us-east-1:123456789012:function:StockCheckerFunction/" your-state-machine-def.json
  

  本地测试的Lambda ARN不需要真实账号ID，用123456789012这个默认测试账号ID即可。

• 修改Makefile添加替换步骤：把替换命令整合到Makefile的测试流程里，确保生成替换后的状态机定义文件再提交给SFL。比如：

  test-stepfunctions:
      sed -e "s/\${StockCheckerFunctionArn}/arn:aws:lambda:us-east-1:123456789012:function:StockCheckerFunction/" state-machine.json > local-state-machine.json
      aws stepfunctions create-state-machine --definition file://local-state-machine.json ...
  

• 用SAM CLI本地启动StepFunctions：放弃手动调用SFL的API，改用sam local start-stepfunctions命令。SAM CLI会自动解析CloudFormation模板里的DefinitionSubstitutions，把占位符替换成本地资源的对应标识，不需要自己处理替换逻辑。

• 用环境变量动态替换：把状态机定义里的占位符改成环境变量格式（比如${STOCK_CHECKER_ARN}），然后用envsubst工具读取环境变量替换后再调用API：

  export STOCK_CHECKER_ARN=arn:aws:lambda:us-east-1:123456789012:function:StockCheckerFunction
  envsubst < state-machine.json > local-state-machine.json
  aws stepfunctions create-state-machine --definition file://local-state-machine.json ...
  

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