使用serverless-offline运行Lambda函数遇模块导入错误求助

核心问题拆解 #

你遇到的两个错误本质是ES模块与CommonJS的兼容冲突：

1. 初始的「Cannot use import statement outside a module」是因为Serverless Offline默认未启用ES模块支持，无法识别package.json中type:module的配置；
2. 改用NodeNext后无法导入UserFunction.js的load，是因为CommonJS模块的module.exports在ES模块环境中会被视为默认导出，而非命名导出。

一、修正TypeScript配置（NodeNext模式） #

调整tsconfig.json，确保ES模块与CommonJS的兼容处理生效：

{
  "compilerOptions": {
    "target": "ESNext",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "esModuleInterop": true,
    "skipLibCheck": true,
    "strict": true,
    "outDir": "./dist",
    "rootDir": "./src"
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules"]
}

• esModuleInterop: 自动处理CommonJS模块的导入兼容，避免命名导入失败；
• outDir: 确保编译后的文件统一输出到dist目录，方便Serverless识别。

二、调整Serverless.yml配置 #

强制Serverless Offline启用ES模块支持，添加以下自定义配置：

service: your-service-name

provider:
  name: aws
  runtime: nodejs20.x
  region: us-east-1

plugins:
  - serverless-offline

functions:
  yourLambdaFunc:
    handler: dist/handler.handler
    events:
      - httpApi:
          path: /test
          method: get

custom:
  serverless-offline:
    httpPort: 3000
    # 关键配置：启用ES模块与子进程执行
    useChildProcesses: true
    esModule: true

• useChildProcesses: 让每个Lambda函数在独立子进程运行，避免模块加载冲突；
• esModule: 明确告知Serverless Offline当前项目使用ES模块规范。

三、修正CommonJS模块的导入方式 #

针对UserFunction.js这类CommonJS文件，在TypeScript中需要用默认导入或命名空间导入，而非解构导入：

// src/handler.ts
// 方式1：默认导入后访问load属性
import UserFunction from '../UserFunction.js';

// 方式2：命名空间导入
// import * as UserFunction from '../UserFunction.js';

export const handler = async (event: any) => {
  const data = UserFunction.load();
  return {
    statusCode: 200,
    body: JSON.stringify({ result: data })
  };
};

原因：CommonJS的module.exports.load会被ES模块解析为default.load，无法直接解构出{load}。

四、确保项目运行流程正确 #

1. 保持package.json的type:module配置不变；
2. 新增编译+启动的脚本，避免直接运行未编译的TypeScript文件：

{
  "type": "module",
  "scripts": {
    "build": "tsc",
    "dev": "npm run build && serverless offline start"
  },
  "engines": {
    "node": ">=20.0.0"
  }
}

3. 运行npm run dev启动本地服务，确保先编译TS为ES模块格式的JS文件，再由Serverless Offline加载。

五、排除其他潜在问题 #

• 所有ES模块中的导入必须带.js扩展名（即使是TS文件，编译后路径要匹配）；
• 升级serverless-offline到最新版本（≥13.3.0），旧版本对Node.js 20的ES模块支持不完善；
• 避免在项目中混合使用require和import语句，保持模块规范统一。

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