Vercelデプロイのエラーを減らす個人開発チェックリスト──ローカルビルドから本番200確認まで

個人開発でVercelにデプロイするときのエラーは、「デプロイしてから気づく」のではなく「デプロイする前に潰せる」種類のものが少なくありません。この記事では、①ローカルでnpm run buildを通す、②環境変数をVercel側（ダッシュボードまたはCLI）にも設定する、③コンテンツ検証をビルドに組み込む、④本番URLがHTTP 200を返すまで確認する──という4項目の実践チェックリストを紹介します。順番に固定手順化すれば、デプロイのたびに慌てる場面を減らせます。

• デプロイ前にローカルでnpm run buildを通し、ビルドエラーはVercelに渡る前に潰す
• 環境変数はローカルの.envだけでは本番に反映されない。ダッシュボード設定と再デプロイが必要
• 「デプロイ完了」は本番URLがHTTP 200を返すのを確認した時点。Vercelの画面のReady表示だけで安心しない

ビルドエラーはローカルで先に潰せる

デプロイ後にVercelのビルドログで赤いエラーを見つけて直す、を繰り返すのは時間の無駄が大きいです。TypeScriptの型エラー、importパスの打ち間違い、依存パッケージの不足といった典型的なビルドエラーは、手元でnpm run buildを実行すればほぼ同じように再現します。

Vercelの公式ドキュメント（Troubleshooting Build Errors）でも、デプロイ前にまずローカルマシンでビルドすることが推奨されています。コードや依存関係に起因する問題を事前に発見できるためです。デプロイは「ローカルでビルドが通ったものを送る」行為にする、というのがチェックリストの最初の項目です。

環境変数はなぜ本番に反映されないのか

環境変数とは、APIキーやデータベース接続情報などをコードの外に置いておく仕組みです。ローカルでは.envファイルに書くのが一般的ですが、このファイルは通常Git管理から外すため、リポジトリ経由のデプロイには含まれません。「ローカルでは動くのに本番では動かない」の定番原因です。

設定方法は2通りあります。

• A案（ダッシュボード）: プロジェクトの Settings → Environment Variables で名前と値を登録する
• B案（CLI）: vercel envコマンドで追加・一覧・ローカルへの取り込み（pull）を行う

どちらでも構いませんが、公式ドキュメントには、環境変数の変更は過去のデプロイには適用されず、新しいデプロイにのみ適用されると明記されています。つまり、反映には再デプロイ（新しいデプロイの作成）が必要です。追加しただけで直った気にならず、再デプロイまでをセットにしてください。

壊れたコンテンツはビルドで止める設計にする

記事やデータを扱うサイトなら、frontmatter（Markdownファイル冒頭に書くタイトルや日付などのメタデータ）やデータのスキーマ検証をビルドに組み込む方法があります。検証に失敗したら意図的にビルドを落とす設計にしておくと、壊れたコンテンツが本番に出る前にVercelのビルド段階で止まってくれます。

実装は、Zodのようなスキーマ検証ライブラリを使う案と、自前の検証スクリプトをbuildコマンドの前段に挟む案のどちらでも成立します。本質は「落ちるべきときにビルドが落ちる」状態を作ることで、ビルドエラーを敵ではなく防波堤として使う考え方です。

デプロイ完了は「本番200」を見るまで

Vercelの画面でデプロイがReadyになっても、本番URLが正しく表示されるかは別問題です。環境変数の不足によるランタイムエラーやドメイン設定の問題は、ビルド成功後にも起こり得ます。

確認方法はここでも2通りです。

• A案（curl）: コマンドラインからHTTPリクエストを送るcurlで本番URLを叩き、ステータスコード200（正常応答）を確認する
• B案（ブラウザ）: 本番URLを実際に開き、トップと主要ページを目視で確認する

機械的に確かめたいならA案、表示崩れまで見たいならB案で、両方やるのが確実です。いずれにせよ「本番URLの200を見るまでがデプロイ」と定義しておくと、「デプロイしたつもりが反映されていなかった」型の事故を検知できます。

自分の運用で事故が消えた話

私は自分のサイト・ゲーム・投稿プラットフォームをVercel上で個人運用しています。以前はデプロイのたびに何かしら小さな事故がありましたが、「ローカルでビルド確認→デプロイ→本番URLの200確認」を毎回の固定手順にしてから、この種の事故は消えました。手順そのものは地味ですが、毎回同じ順番で機械的にやることに意味があると感じています。

このチェックリストの適用範囲

• このチェックリストで全てのエラーが防げるわけではありません。実行時にだけ起こるエラーや、外部サービスの障害・サスペンドに起因する問題は残ります
• ローカルとVercelでNode.jsのバージョンが異なると、ローカルで通ったビルドが本番で落ちることがあります。プロジェクト設定でバージョンを揃えるのが安全です
• 本記事はNext.jsなどNode.js系プロジェクトを想定しています。他のフレームワークでも考え方は流用できますが、コマンドは異なります
• Vercelの画面構成や仕様は更新されるため、最終的には公式ドキュメントを確認してください

参照したVercel公式ドキュメント

• Vercel Docs: Troubleshooting Build Errors
• Vercel Docs: Environment variables
• Vercel Docs: vercel env