如何通过esbuild构建特定平台的sharp并部署到Lambda NodejsFunction？

问题描述 #

尝试部署依赖sharp进行图像处理的AWS Lambda函数，要求使用esbuild构建，禁止使用Docker。当前CDK中NodejsFunction的配置代码如下：

const processUploadedImageLambdaFunction = new NodejsFunction(
    this,
    `${deployEnv()}_processUploadedImage`,
    {
      runtime: lambda.Runtime.NODEJS_18_X,
      entry: `${__dirname}/../lambda-fns/lambdas/processUploadedImage/index.ts`,
      bundling: {
        target: "node18",
        sourceMap: true,
        sourceMapMode: SourceMapMode.INLINE,
        sourcesContent: false,
        externalModules: ["sharp"],
        nodeModules: ["sharp"],
        command: ["npm rebuild sharp --arch=x64 --platform=linux sharp"],
      },

      insightsVersion,
      logRetention,
      memorySize: 3008,
      timeout: cdk.Duration.seconds(30),
      environment: {
        ...config,
      },
    },
)

函数运行时抛出以下异常：

{
    "errorType": "Error",
    "errorMessage": "\nSomething went wrong installing the \"sharp\" module\n\nCannot find module '../build/Release/sharp-linux-x64.node'\nRequire stack:\n- /var/task/node_modules/sharp/lib/sharp.js\n- /var/task/node_modules/sharp/lib/constructor.js\n- /var/task/node_modules/sharp/lib/index.js\n- /var/task/index.js\n- /var/runtime/index.mjs\n\nPossible solutions:\n- Install with the --verbose flag and look for errors: \"npm install --ignore-scripts=false --verbose sharp\"\n- Install for the current linux-x64 runtime: \"npm install --platform=linux --arch=x64 sharp\"\n- Consult the installation documentation: https://sharp.pixelplumbing.com/install",
    "stack": [
        "Error: ",
        "Something went wrong installing the \"sharp\" module",
        "",
        "Cannot find module '../build/Release/sharp-linux-x64.node'",
        "Require stack:",
        "- /var/task/node_modules/sharp/lib/sharp.js",
        "- /var/task/node_modules/sharp/lib/constructor.js",
        "- /var/task/node_modules/sharp/lib/index.js",
        "- /var/task/index.js",
        "- /var/runtime/index.mjs",
        "",
        "Possible solutions:",
        "- Install with the --verbose flag and look for errors: \"npm install --ignore-scripts=false --verbose sharp\"",
        "- Install for the current linux-x64 runtime: \"npm install --platform=linux --arch=x64 sharp\"",
        "- Consult the installation documentation: https://sharp.pixelplumbing.com/install",
        "    at Object.<anonymous> (/var/task/node_modules/sharp/lib/sharp.js:31:9)",
        "    at Module._compile (node:internal/modules/cjs/loader:1254:14)",
        "    at Module._extensions..js (node:internal/modules/cjs/loader:1308:10)",
        "    at Module.load (node:internal/modules/cjs/loader:1117:32)",
        "    at Module._load (node:internal/modules/cjs/loader:958:12)",
        "    at Module.require (node:internal/modules/cjs/loader:1141:19)",
        "    at require (node:internal/modules/cjs/helpers:110:18)",
        "    at Object.<anonymous> (/var/task/node_modules/sharp/lib/constructor.js:8:1)",
        "    at Module._compile (node:internal/modules/cjs/loader:1254:14)",
        "    at Module._extensions..js (node:internal/modules/cjs/loader:1308:10)"
    ]
}

需要解决的问题：

• 当前配置遗漏了什么？
• 如何通过esbuild为特定平台构建sharp并部署到NodejsFunction？
• 是否可以仅使用基础esbuild实现，避免Docker和Layers？

解决方案 #

核心问题分析 #

1. command参数写法错误，额外重复了sharp参数，导致命令执行异常。
2. externalModules和nodeModules同时设置存在冲突，CDK的NodejsFunction在处理外部依赖时，只需通过externalModules标记即可自动安装对应模块。
3. 未设置npm环境变量指定目标平台和架构，导致sharp安装时默认使用本地平台的二进制文件，而非Lambda需要的Linux x64版本。

修改后的配置代码 #

const processUploadedImageLambdaFunction = new NodejsFunction(
    this,
    `${deployEnv()}_processUploadedImage`,
    {
      runtime: lambda.Runtime.NODEJS_18_X,
      entry: `${__dirname}/../lambda-fns/lambdas/processUploadedImage/index.ts`,
      bundling: {
        target: "node18",
        sourceMap: true,
        sourceMapMode: SourceMapMode.INLINE,
        sourcesContent: false,
        externalModules: ["sharp"], // 标记sharp为外部依赖，不参与esbuild打包
        environment: {
          // 设置npm环境变量，指定Lambda运行的平台和架构
          'npm_config_platform': 'linux',
          'npm_config_arch': 'x64'
        },
        // 执行标准的生产依赖安装命令，sharp会自动适配指定平台
        command: ['npm', 'install', '--production']
      },

      insightsVersion,
      logRetention,
      memorySize: 3008,
      timeout: cdk.Duration.seconds(30),
      environment: {
        ...config,
      },
    },
)

关键调整说明 #

• 移除nodeModules配置：externalModules已经明确告知esbuild不打包sharp，CDK会在bundling阶段自动安装该外部依赖，无需重复配置。
• 添加npm环境变量：通过npm_config_platform和npm_config_arch强制npm在安装sharp时下载/编译Linux x64版本的二进制文件，匹配Lambda的运行环境。
• 修正command命令：使用npm install --production即可完成依赖安装，无需手动执行rebuild，sharp会根据环境变量自动处理平台适配。

验证方法 #

部署完成后，可通过Lambda控制台查看函数代码包中的node_modules/sharp/build/Release目录，确认存在sharp-linux-x64.node文件，此时函数即可正常调用sharp的图像处理API。

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