[Vercel] Node.js のバージョンアップ

Vercel から「[Action Required] Node.js 18 is being discontinued on Monday, September 1st, 2025」というメールがきた。

2025/4/30の Node.js 18 のサポート終了に伴い、Vercel で Node.js 18 で動作している環境も使用できなくなる通知がきました。アップグレードしてね、と書いてあった。

https://vercel.com/docs/functions/runtimes/node-js/node-js-versions#setting-the-node.js-version-in-project-settings

Next.js で Vercel 環境を使っていたので、Node.js 18 to 22.x へバージョンアップをする作業をすすめることにした。

サポート終了すると、セキュリティパッチが一切提供されなくなったり、バグ修正・パフォーマンス改善もされないので、安全性や安定性の面でリスクが大きくなるため、きちんと運用していくなら必須の対応だ。

Vercel 環境を Node.js 18.x から 22.x へアップグレードする

作業は大きく分けて「①ローカル開発環境の準備」「②プロジェクトの設定変更と更新」「③動作確認とデプロイ」の3ステップになります。

ローカル開発環境の Node.js バージョンを 22.x に設定

事前準備

万が一問題が発生した際に、すぐに元の状態に戻せるように、Gitで新しいブランチを作成してから作業を開始します。
また、Vercel で Preview 機能を使っており、Pull RequestしたタイミングでPreview環境を作ってくれるので便利です。

# main ブランチへ移動
git checkout main

# Gitリポジトリの最新の状態を取得
git pull

# Node.jsアップグレード用の新しいブランチを作成して切り替え
git checkout -b feature/upgrade-node-22

開発環境の Node.js をアップグレードする

開発環境の Node.js 環境をアップグレードします。nvmなどを使用していると便利ですが、私の環境は Mac で、/usr/local/bin/node にある Node.js を使ったのでちょっと手間でした。

これを、nodebrew を使うように変更してからアップグレードします。

nodebrewのパスを正しく設定する

以下のコマンドを実行して、~/.zshrc ファイルに nodebrew のパス設定を書き込みます。

echo 'export PATH=$HOME/.nodebrew/current/bin:$PATH' >> ~/.zshrc

設定をターミナルに反映させます。(ターミナルを再起動すれば反映させられるので、確実です。)

source ~/.zshrc

nodebrew で使用するバージョンをセットします。

nodebrew use v22.17.0

Node.js のバージョンを確認します。v22.17.0 になっていることを確認します。

node -v

依存パッケージの更新とバージョンの調整

Vercel に Node.js 22 を使うことを指示するため、package.json に engines を追加します。

{
  // ...
  "engines": {
    "node": "22.x"
  },
  // ...
}

npm-check-updates (ncu) を使って、プロジェクトの依存関係を最新化します。
これは便利ですが、何かエラーが起こった時に原因の追及が大変なので、本来は一つづパッケージの更新内容などチェックがおすすめです。

npx npm-check-updates -u

環境の不整合をなくすため、一度すべてのパッケージとキャッシュを削除し、クリーンな状態で再インストールします。

# 古いキャッシュと依存関係を完全に削除
rm -rf .next node_modules yarn.lock

# yarnのキャッシュもクリア
yarn cache clean

# パッケージを再インストール
yarn install

ローカルでの動作確認

ローカルで yarn dev して全てのページでエラーがなく動作することを確認します。
packageのバージョンアップにより非推奨になるメソッドやeslintの更新によるエラーも出ることがあるので確認します。

最後に yarn build してビルドが通るか確認します。

# 開発サーバーを起動してブラウザで動作確認
yarn dev

# ビルドが通るか確認
yarn build

GitHub Actionsのワークフローを修正

GitHub Actions で Vercel へ自動デプロイするために yaml （.github/workflows/*.yml）を定義していたので、これも修正します。
actions/setup-node@v4 を追加して、CI環境も Node.js v22.x になるようにします。

steps:
  - uses: actions/checkout@v2

  # このステップを追加
  - name: Setup Node.js
    uses: actions/setup-node@v4
    with:
      node-version: '22.x'

  - name: Install Vercel CLI
    # ... 以降のステップ

Vercel で GitHubActions は下記記事で書いてます。

Tsukurue

[Vercel]GitHub Actionsを利用して権限を制御する。 | Tsukurue サーバーはVercel、ソースコードはNext.jsで動かしていた。運用中に、Vercelの管理者とソースコードの管理者が別れ、それぞれがアクセスできる権限を分ける必要が出てきた…

変更をプッシュしてPRを作成

すべての変更をGitにコミットし、GitHub にプッシュして PullRequest を作成します。

※ このタイミングでは、Vercel の環境をアップグレードしていないので CI が失敗します。後に書いてしまいましたが、事前後述する「Vercel 環境を Node.js 18.x から Node.js 22.x へアップグレードする」を実施します。

# すべての変更をステージング
git add .

# コミット
git commit -m "feat: Upgrade to Node.js 22 and apply necessary fixes"

# ブランチをプッシュ
git push origin feature/upgrade-node-22

Vercel のPreview版で動作確認

CIが動作すると、VercelにPreview版として自動デプロイされます。
Vercel の Deployments -> Options (3点リーダー) -> Visit でPreview 版へアクセスします。動作確認して問題ないことを確認しておきます。

Vercel 環境を Node.js 18.x から Node.js 22.x へアップグレードする

Vercelのダッシュボードから該当のプロジェクトページへアクセスし、Settings -> Build and Deployment をクリックします。

[Node.js Version]で、18.ｘから 22.x へ更新します。

22.x へ更新します。

これをしないとPR時にエラーになる。ので少し焦る。

PR時、下記エラーがに出たときは、

Run vercel build --token=***
Vercel CLI 44.5.0
WARN! Build not running on Vercel. System environment variables will not be available.
Warning: Due to "engines": { "node": "22.x" } in your `package.json` file, the Node.js Version defined in your Project Settings ("18.x") will not apply, Node.js Version "22.x" will be used instead. Learn More: http://vercel.link/node-version
Installing dependencies...
yarn install v1.22.22
[1/5] Validating package.json...
error kyoto-sanjo-degital-map@0.1.0: The engine "node" is incompatible with this module. Expected version "22.x". Got "20.19.3"
error Found incompatible module.
info Visit https://yarnpkg.com/en/docs/cli/install for documentation about this command.
Error: Command "yarn install" exited with 1
Error: Process completed with exit code 1.

Vercelのバージョンを上げて、jobを再実行しましょう。 or　空コミットして動作させます。