基于Docker化LocalStack、TypeScript和AWS CDK v2的Lambda热重载问题

核心问题分析 #

代码已同步到LocalStack容器的/var/task目录，但Lambda调用仍返回旧响应，主要原因集中在这几点：

1. Lambda执行容器被复用，未加载新代码；
2. CDK的NodejsFunction默认自动打包，覆盖了挂载的本地代码；
3. Node.js模块缓存导致旧代码未更新；
4. 环境变量配置大小写或参数冲突。

解决方案1：调整Lambda执行器配置 #

修改docker-compose.yml中的Lambda执行器及相关环境变量，确保每次调用加载最新代码：

environment:
  # ... 保留其他原有配置
  - LAMBDA_EXECUTOR=docker
  - LAMBDA_RELOAD_CODE=true  # 改为小写，LocalStack对大小写敏感
  - LAMBDA_REMOVE_CONTAINERS=true  # 改为小写，确保调用后销毁容器

• docker执行器会在每次调用后销毁容器，避免复用旧容器导致的代码缓存；
• 修正环境变量值的大小写，确保LocalStack能正确识别配置。

解决方案2：修改CDK Lambda配置，禁用自动打包 #

你当前使用的lambda.NodejsFunction会自动打包指定的TS文件，可能覆盖本地挂载的build目录。改用普通lambda.Function类，直接指向已打包的build目录：

import * as lambda from 'aws-cdk-lib/aws-lambda';
import * as path from 'path';

// 替换原NodejsFunction实例化代码
const fnHello = new lambda.Function(this, "FnHello", {
  runtime: lambda.Runtime.NODEJS_20_X, // 匹配你的Node.js版本
  handler: "hello.handler", // 对应build目录下hello.js中的handler函数
  code: lambda.Code.fromAsset(path.join(__dirname, "../functions/build")),
  environment: {
    TABLE_NAME: table.tableName,
  },
});

这样CDK会直接将本地build目录作为Lambda代码源，配合LocalStack的挂载配置，确保代码更新后能被读取。

解决方案3：禁用Node.js模块缓存（适用于保留容器复用场景） #

如果需要保留docker-reuse执行器以提升开发效率，可在Lambda代码中添加禁用缓存的逻辑，确保每次调用加载最新文件：

// 在hello.js的handler函数开头添加
delete require.cache[module.id];

export const handler = async (event) => {
  // 你的业务逻辑
};

注意：此方法仅用于开发环境，生产环境禁用会影响性能。

解决方案4：清理LocalStack持久化缓存（可选） #

若启用了PERSISTENCE=1，旧的Lambda代码可能被缓存到./volume目录。可临时关闭持久化测试，或手动清理缓存：

# 删除LocalStack持久化缓存目录
rm -rf ./volume
# 重启LocalStack容器
docker-compose down && docker-compose up -d

验证步骤 #

1. 启动esbuild watch：npm run watch，修改hello.ts后确认functions/build/hello.js已更新；
2. 进入LocalStack容器验证同步：docker exec backend cat /var/task/hello.js；
3. 调用Lambda函数，检查响应是否为最新代码；
4. 查看LocalStack日志：docker logs backend，确认Lambda启动时加载了最新文件路径。

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