如何在Serverless ESBuild中配置Node Loader解决.node文件加载错误

核心思路 #

ESBuild本身不支持编译或打包.node格式的原生绑定模块，这类模块与特定操作系统、CPU架构强绑定，只能原样复制到打包后的部署包中，同时要确保：

1. ESBuild不尝试打包该模块（标记为外部依赖）
2. 原生模块的架构与Lambda运行环境匹配（比如Lambda用Linux ARM64，就不能用本地Darwin ARM64的包）
3. 复制后的模块路径与代码引用路径一致

具体配置方案 #

1. 调整Serverless + ESBuild配置（serverless.yml） #

在serverless.yml中配置serverless-esbuild插件，标记原生模块为外部依赖，并添加复制规则：

service: your-lambda-service

plugins:
  - serverless-esbuild

provider:
  name: aws
  runtime: nodejs18.x # 替换为你使用的Node.js版本
  architecture: arm64 # 或x86_64，需与原生模块架构严格匹配

custom:
  esbuild:
    bundle: true
    minify: true # 生产环境开启，调试阶段可关闭
    external:
      - nodejs-polars # 告诉ESBuild不要处理这个原生模块
    copy:
      # 复制对应架构的原生模块文件到打包后的node_modules目录，保持原路径结构
      - from: 'node_modules/nodejs-polars-*/**/*.node'
        to: './node_modules/[path]'

2. 安装匹配Lambda架构的原生模块 #

本地开发架构（比如Darwin ARM64）和Lambda运行架构大概率不同，必须安装对应Lambda环境的包。以pnpm为例，执行：

# Lambda用ARM64架构时执行
pnpm add nodejs-polars --platform=linux --arch=arm64

# Lambda用x86_64架构时执行
pnpm add nodejs-polars --platform=linux --arch=x64

也可以在package.json中添加脚本简化操作：

{
  "scripts": {
    "install:lambda-arm64": "pnpm add nodejs-polars --platform=linux --arch=arm64",
    "install:lambda-x64": "pnpm add nodejs-polars --platform=linux --arch=x64"
  }
}

3. 验证打包结果 #

执行serverless package后，检查.serverless/your-service.zip（或对应函数的子目录），确认node_modules下存在对应的.node文件，且路径与本地一致。

关键注意事项 #

• 不要尝试用ESBuild的loader处理.node文件：ESBuild没有官方支持的.node loader，这类模块无法被编译，只能原样复制。
• 架构不匹配会导致Lambda运行报错：如果部署的原生模块和Lambda架构不一致，会出现Error: Cannot find module或invalid ELF header错误，务必保证架构匹配。
• 若使用pnpm的workspace或lockfile，需确保lockfile中记录了对应架构的包信息，避免部署时拉错版本。

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