AWS CDK NodejsFunction を使う時は、npm以外のパッケージマネージャーを使おう

AWS CDKのNodejsFunctionを使う際、npmのバグでCI環境のビルドが失敗することがあります。この問題はpnpmなど別のパッケージマネージャーに切り替えることで簡単に解決できます。

AWS CDK で NodejsFunction を使っていると、ローカル環境では正常に動作するのに CI 環境でだけビルドが失敗する現象に遭遇することがあります。この問題は npm の既知のバグに起因しており、パッケージマネージャーを pnpm などのnpm以外に変更することで解決できます。

遭遇した問題

AWS CDK の NodejsFunction を使用してアプリを開発することが多いです。macOS で開発している環境で開発を行い、CircleCI / GitHub Actionなどで CI でデプロイすると、 npm ci コマンドを実行するステップで次のようなエラーが発生することがあります。

Error: Cannot find module @esbuild/linux-x64-gnu
    at requireWithFriendlyError (/node_modules/esbuild/lib/main.js:...)

厄介なのがこのエラーを再現するために npm ci コマンドをローカル環境で実行しても、問題なく動作するためことです。エラーメッセージを見ると esbuild が Linux 用のバイナリを見つけられていないらしいので、「macOS環境でのみ npm ci コマンドが成功する状況」であると推測ができます。

npm/cli#4828 のバグが原因らしい

調査すると、npm の Issue #4828 が該当するものだった様子です。2022年4月に報告され、2025年1月現在も未解決でした。

Claudeに内容をざっくり解説させたところ、以下のような挙動が起きているらしいです。

npm/cli#4828 バグは、node_modules ディレクトリが既に存在する状態で package-lock.json を再生成すると発生します。この状態で npm install を実行すると、lockfile には現在のプラットフォーム用の optional dependencies のみが記録されてしまいます。npm ci は lockfile に記載されたパッケージを厳密にインストールするため、記載のない optional dependencies は警告なくスキップされます。

Issue #4828 の内容をClaudeが要約・解説したもの

node_modulesディレクトリを削除してからnpm iすれば解決しそうな感じはします。ただ、npm i ANY_PACKAGEでライブラリを追加するたびにこれを実行するのは、正直オーバーヘッドが気になるところです。

npm以外、例えばpnpmへ移行する

エラーの原因がnpmのIssueであることがわかったので、ワークアラウンドはとてもシンプルです。

NodejsFunctions（というかesbuild）を使うCDKスタックでは、npm以外を利用する

Dockerやdevcontainerなどを使い、npm iをLinux上で実行する

Issueの解決に参加する

今回は個人開発で時間もあまりかけれないため、別のパッケージマネージャーを使うことにしました。

CI 環境の設定も更新します。CircleCI を使用している場合、次のように node orb の設定を２行ほど変更しておきます。

version: 2.1

orbs:
  node: circleci/[email protected]

jobs:
  build:
    executor: node/default
    steps:
      - checkout
      - node/install-packages:
          pkg-manager: pnpm
      - run:
          name: Deploy
          command: pnpm cdk deploy

pkg-manager: pnpm を指定することで、CircleCI が自動的に pnpm をインストールして使用します。

移行後は CI 環境で正常にビルドが完了することを確認しましょう。esbuild が必要とする Linux 用バイナリが正しくインストールされ、NodejsFunction のバンドリングが成功します。

まとめ

AWS CDK の NodejsFunction を macOS と Linux の複数環境で使用する場合、npm の既知のバグ（npm/cli#4828）により package-lock.json が不完全に記録され、CI 環境でのビルドが失敗することがあります。この問題は npm 固有のものであり、2026年1月現在も未解決です。

NodejsFunction を使用するプロジェクトでクロスプラットフォーム開発を行う場合は、pnpm など、npm以外のパッケージマネージャーを使う方が、今のところは安全そうです。