如何在本地开发中使用Lambda共享工具层实现跨环境兼容

统一导入规则 #

AWS环境中，绑定的Lambda层内容会默认挂载到/opt目录下，结合你的项目结构，线上环境可以直接通过绝对路径导入工具函数，所有Lambda代码统一使用该写法即可：

// TS/JS 通用导入写法
import { yourUtilFunction } from '/opt/nodejs/utils';

该写法在线上AWS环境原生支持，无需额外配置。

本地开发环境适配 #

分两种常见开发场景配置：

场景1：使用sam-beta-cdk本地运行（sam local invoke/start-api） #

你只需要在CDK代码中正确定义层并关联到对应Lambda，SAM会自动完成本地层路径映射，无需额外配置：

// CDK 定义示例
import * as lambda from 'aws-cdk-lib/aws-lambda';
import * as path from 'path';

// 定义公共工具层
const commonUtilsLayer = new lambda.LayerVersion(this, 'CommonUtilsLayer', {
  code: lambda.Code.fromAsset(path.join(__dirname, '../layers/layer-name')),
  compatibleRuntimes: [lambda.Runtime.NODEJS_18_X, lambda.Runtime.NODEJS_20_X],
  description: '多Lambda共用工具层'
});

// Lambda 定义时绑定层
const featureLambda = new lambda.Function(this, 'FeatureLambda', {
  runtime: lambda.Runtime.NODEJS_20_X,
  code: lambda.Code.fromAsset(path.join(__dirname, '../lambdas/feature/lambda-name')),
  handler: 'lambda.handler',
  layers: [commonUtilsLayer] // 绑定层后SAM本地运行会自动映射路径
});

配置完成后sam local运行的导入逻辑和线上完全一致。

场景2：本地直接运行TS/JS文件（不通过SAM容器） #

需要配置路径映射让本地开发环境识别/opt开头的导入路径：

1. 配置tsconfig.json路径别名，解决TS类型识别和编译问题：

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "/opt/nodejs/*": ["./layers/layer-name/nodejs/*"]
    },
    "include": ["lambdas/**/*", "layers/**/*"] // 把层目录加入编译范围，获取类型提示
  }
}

2. 配置运行时NODE_PATH环境变量，让Node.js能找到对应模块：
   可以直接在启动命令中添加，也可以配置到package.json脚本中：

{
  "scripts": {
    "local:run:lambda": "NODE_PATH=./layers/layer-name node lambdas/feature/lambda-name/lambda.js"
  }
}

Windows环境下修改环境变量写法即可：

$env:NODE_PATH="./layers/layer-name"; node lambdas/feature/lambda-name/lambda.js

可选兜底兼容方案 #

如果不想修改本地环境配置，也可以在导入时增加异常捕获兜底，不过更推荐使用上述路径映射方案，不需要修改业务代码：

let utils;
try {
  // 优先匹配线上环境路径
  utils = require('/opt/nodejs/utils');
} catch (e) {
  // 本地兜底用相对路径导入
  utils = require('../../../../layers/layer-name/nodejs/utils');
}

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