GitHub Actions Ubuntu x86-64环境下esbuild安装因缺失android-arm失败

我有一个基于Node.js 14的AWS Lambda函数，使用serverless-bundle进行打包（该工具内部依赖esbuild）。本地Mac M1环境中，无论执行npm install还是npm ci（即使删除node_modules）都能正常安装。但在部署到AWS Lambda x86-64容器的GitHub Actions工作流中，使用ubuntu-latest环境执行npm ci时立即报错：

Run npm ci
npm ERR! @esbuild/android-arm not accessible from esbuild

我的疑问：

1. GitHub Actions的ubuntu-latest环境为何需要@esbuild/android-arm二进制包？
2. 若问题源于本地Mac M1生成的package-lock.json（包含@esbuild/darwin-arm64条目）与目标架构不兼容，如何在不Docker化整个开发环境的前提下生成适配的package-lock.json？

注：我发现相关issue建议升级到Node.js 16，但升级会导致环境混乱，暂不想升级；另外注意到package-lock.json中esbuild将@esbuild/android-arm等列为依赖，但esbuild自身的package.json里这些是optionalDependencies。

疑问1的原因 #

这个问题本质是Node.js 14默认搭配的npm 6对optionalDependencies的处理逻辑缺陷：

• esbuild为跨平台兼容，将各架构的二进制包声明为optionalDependencies，正常情况下npm只会安装当前环境对应的架构包，其他包会被忽略。
• 但npm 6处理跨平台生成的package-lock.json时，会错误地把lock文件中记录的所有optional依赖视为必填项。你在Mac M1（arm64）环境生成的lock文件包含@esbuild/darwin-arm64，同时npm 6还会将esbuild的其他optional架构包（比如@esbuild/android-arm）纳入依赖解析范围，导致在ubuntu x86-64环境中尝试拉取这些无关包，最终因找不到适配版本报错。

疑问2的解决方案 #

以下几种方法无需Docker化即可解决：

方法1：本地生成兼容的package-lock.json #

删除本地现有node_modules和package-lock.json，执行以下命令生成适配linux x86-64环境的lock文件：

npm install --platform=linux --arch=x64 --no-optional

• --platform=linux和--arch=x64指定生成适配目标环境的依赖记录
• --no-optional确保optionalDependencies不会被写入lock文件，避免后续安装时解析无关架构包
  提交新生成的package-lock.json到仓库，GitHub Actions执行npm ci即可正常安装。

方法2：修改GitHub Actions安装命令 #

直接在Actions的npm ci命令中添加--no-optional参数，跳过optional依赖的安装：

- name: Install dependencies
  run: npm ci --no-optional

注意：需确认项目没有依赖其他必须的optional包，否则会影响功能。

方法3：通过环境变量强制适配目标架构 #

在GitHub Actions的安装步骤中添加环境变量，让npm模拟linux x64环境解析依赖：

- name: Install dependencies
  env:
    npm_config_platform: linux
    npm_config_arch: x64
  run: npm ci

此方法会让npm自动忽略无关架构的optional包，避免报错。

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