VercelのNode.jsバージョンを変えたのに反映されない。Redeployはビルド設定のスナップショットを使い回す

こんにちは、Webサービス開発者のyuku_tasです。

簡単なプロフィール: MoldSpoon Inc.代表。開業から15年、業界に携わって20年。Webサイト/iOS/Androidアプリ開発から、
データ分析業務・コンサル業務、ベンチャーから保険会社まで様々な案件を個人会社の形で請け負ってまいりました。
詳しくはこちら

はじめに

ある日、VercelのビルドがNode.js 18の提供終了で落ちました。

Error: Node.js Version "18.x" is discontinued and must be upgraded.

やることは明白です。設定画面でNode.jsのバージョンを上げればいい。そう思って設定を変え、落ちたデプロイをRedeployしました。

同じエラーで落ちました。

設定画面を見ても、ちゃんと新しいバージョンになっています。それでもRedeployすると18のまま。原因は、Redeployが「そのデプロイが作られた時点のビルド設定」を再利用することでした。

原因：Redeployは過去の設定ごと復元する

Vercelのデプロイは、作成された時点でビルド設定のスナップショットを持ちます。Node.jsのバージョン、ビルドコマンド、環境変数の一部などです。

Redeployは名前の通り「もう一度デプロイする」機能ですが、実際にやっているのはそのスナップショットでのビルドをやり直すことです。だから、あとから設定画面を変えても効きません。

つまりこうなります。

設定を変えたら、新しいコミットをpushして新規デプロイを起こす。 これが答えです。

変更するものが無ければ空コミットで構いません。

git commit --allow-empty -m "Node.jsバージョンの設定変更を反映するため再デプロイする"
git push

私は実際にこの内容のコミットを打ちました。「設定を変えたのに反映されない」で悩んだ痕跡がリポジトリに残っています。

設定欄が見つからない場合

もうひとつハマりどころがあります。Node.js Versionの設定欄の場所が移動しました。

• 以前: Settings → General
• 現在: Settings → Build and Deployment

Generalを何度スクロールしても見つからず、「このプロジェクトだけ設定欄が無いのでは」と疑いました。移動しただけです。

より確実な方法：package.jsonのenginesで固定する

ダッシュボードの設定は、プロジェクトの外にある状態です。リポジトリを見てもバージョンが分かりませんし、複数人で触っていると誰がいつ変えたのか追えません。

package.jsonのengines.nodeに書いておけば、リポジトリ側が情報源になります。

{
  "name": "your-app",
  "private": true,
  "engines": {
    "node": "24.x"
  }
}

Vercelはこれを読んでビルドに使うNode.jsを決めます。設定画面とリポジトリで食い違ったときに、どちらが正なのか迷わなくて済むのが一番の利点です。

うちではこれを「唯一の情報源」と決めて、運用メモにもそう書きました。

ローカルでenginesに弾かれるとき

enginesを書くと、ローカルのNodeがそれより古い場合にインストールやスクリプト実行が止まります。

error your-app@0.1.0: The engine 

すぐに上げられない事情があるなら、yarnならこう回避できます。

yarn install --ignore-engines

yarn devが弾かれる場合は、npx next devのように直接叩けば動きます（環境変数の指定を忘れないでください）。ただしそれはローカルの話で、本番のビルドはenginesの通りに動きます。ローカルだけ古いままにしておくと、手元で通ったものが本番で落ちる状況を作りかねないので、あくまで一時しのぎです。

ネイティブ依存があるならビルドキャッシュも外す

Node.jsのバージョンを上げるとき、ネイティブモジュール（C++でビルドされるパッケージ）を使っているなら、もう1つ注意点があります。

Redeployのダイアログにある「Use existing Build Cache」のチェックを外してください。

チェックが入ったままだと、旧バージョンのNodeでコンパイルされた成果物が再利用されます。 新しいNodeで通るかどうかの検証になりません。

ネイティブモジュールはNodeのメジャーバージョンが変わるとABIが変わり、そのままでは動きません。実際にうちはこれで詰まりました。

いつまで上げ続ければいいのか

Node.jsのバージョンは放っておいても、EOL（サポート終了）を迎えるとVercel側が新規ビルドを打ち切ります。 今回の18がまさにそれでした。

つまり「動いているから触らない」は選べません。EOLの日付だけ把握して、余裕をもって上げるのが結局いちばん安く済みます。Node 24のEOLは2028年4月です。

よくある質問（FAQ）

Q. 設定画面とengines.nodeが食い違ったらどちらが勝ちますか？

うちはengines.nodeを書いた状態で運用していて、そちらの通りにビルドされています。

ただ、どちらが勝つかを覚えるより食い違わせないほうが安全です。enginesを書くと決めたなら、設定画面のほうは「同じ値にしておく」か、以後見ないと決めてしまうのがいいと思います。

Q. 環境変数を変えたときもRedeployで反映されませんか？

環境変数はスナップショットの扱いが異なり、Redeployでも新しい値が入る場合があります。ただ確実なのは新しいデプロイを起こすことです。

うちでは環境変数を追加したあと「SMTPの環境変数設定を反映するため再デプロイする」という空コミットを打っています。数十秒で終わるので、迷ったらpushするのが早いです。

Q. Node.jsを上げたらビルド時間が伸びました

バージョンを変えるとビルドキャッシュが効かなくなるため、1回目は必ず遅くなります。 うちの規模（ページ50本以上）で、キャッシュ無しは約12分、キャッシュ有りだと約1分40秒でした。

2回目以降も遅いままなら、キャッシュではなく依存側の問題を疑ってください。

まとめ

• VercelのNode.jsバージョンを変えたら、新しいコミットをpushする。Redeployでは反映されない
• Redeployはデプロイ作成時のビルド設定スナップショットを再利用する
• 設定欄はGeneralではなくBuild and Deploymentに移動している
• 迷わないためにpackage.jsonの**engines.nodeをリポジトリ側の情報源にする**
• ネイティブ依存があるなら、Redeploy時に**「Use existing Build Cache」を外す**

「設定を変えたのに反映されない」と感じたら、まずそれが新規デプロイなのかRedeployなのかを確認してみてください。

この記事が何かのお役に立てれば幸いです。
最後までお読みいただきありがとうございました！