「見積もり1時間、実績8時間」——このフレーズに心当たりのあるエンジニアは少なくないはず。本記事は、Qiitaに投稿された実録デプロイ失敗談を元に、本番環境特有の落とし穴と事前に防げたミスを整理する。Next.js + AWS Lambda 構成で開発しているチームには特に刺さる内容だ。
背景：なぜ「1時間」のはずが「8時間」になったのか
仮完成報告会の前日、チームメンバーに触れるデータを本番環境に投入する作業が発生した。普段はローカルで seed ファイルを使い一括生成しているため、「同じことを本番でやるだけ」という認識だった。しかし本番環境は、ローカルとはまったく異なる地雷原だった。
筆者は6つの誤算を3カテゴリに分類している。
- 本番環境特有のエラー：誤算1（認証メール）、誤算2（Lambdaライブラリ）
- ローカルで防げたはずのエラー：誤算3（謎のリダイレクト）、誤算4（404）、誤算5（メイン機能停止）
- 焦りが招いた判断ミス：誤算6（本番でのビルド実行）
技術的に最も重要な教訓：Lambdaで動かすライブラリの選び方
誤算2が特に技術的な学びとして深い。PDF解析に使っていた pdfjs-dist が、Lambda（Node.jsランタイム）上で動作しなかった。
原因は pdfjs-dist がブラウザの DOM API（DOMMatrix、Path2D など）に依存していること。ブラウザ前提で設計されたライブラリはLambdaでは動かない。
# Lambda環境でのエラー例（イメージ）
ReferenceError: DOMMatrix is not defined
at new PDFPageProxy (/var/task/node_modules/pdfjs-dist/...)解決策は pdf2json（純粋Node.js実装）に戻すこと。Lambda上でライブラリを使う際は「ブラウザ依存か・純粋Node.js実装か」を必ず確認する習慣が欠かせない。
ローカルで防げたはずの3つのミス
誤算3〜5はすべて「ローカル環境でのステージング確認不足」が根本原因だ。具体的には：
- 誤算3：有料プランユーザーのはずなのに、フリープラン制限画面にリダイレクトされた（プラン判定ロジックのバグ）
- 誤算4：本番でのみ発生する404（パス設定やルーティングの差異）
- 誤算5：メイン機能が丸ごと停止（上記バグの連鎖）
これらは「本番同等の環境でseedを流すテスト」を1回やっておくだけで発見できた可能性が高い。本番デプロイ前にステージング環境でseedを一度流すというプロセスを標準化する価値は大きい。
まとめ：チェックリストとして使える教訓
この記録から抽出できる実践的なチェック項目：
- Lambdaで使うライブラリはブラウザ依存がないか確認する
- 認証フロー（メール送信含む）を本番環境で事前検証する
- seedファイルはステージング環境で一度試してから本番適用する
- 焦っているときほど「本番でビルドする」などの判断を慎重にする
- デプロイ作業の見積もりにはバッファを2〜3倍見ておく
元記事では誤算4〜6の詳細や、各誤算でどう判断して乗り越えたかも丁寧に書かれている。「次の自分が同じ罠を踏まないための記録」として書かれた誠実な技術ブログで、デプロイ作業を控えているチームに一読を強くすすめたい。