Vercel「pushしても反映されない」の見えない原因と、Next.jsビルド検証の穴

症状

ユーザーから「送信した内容/変更した内容が反映されていない気がする」と報告される。Vercelプロジェクトは存在し、過去にデプロイもされている。コードにもDBにも異常はない。

根本原因1: Vercelプロジェクトが「link」されていても「git連携」は別軸

Vercelプロジェクトが対象リポジトリに vercel link 済みで、過去に vercel --prod で本番反映された実績があっても、GitHub側のリポジトリへのpushで自動デプロイされるとは限らない。この2つは別の設定である。

• 確認: https://github.com/settings/installations を開き、"Vercel" が Installed GitHub Apps に無ければ、GitHub側でVercelがそのアカウント/組織に対して何のアクセス権も持っていない（プロジェクトのgit連携設定がどうなっていても無意味）。
• vercel git connect <repo-url> --yes を実行してみると、この状態では次のようなエラーになる: Error: Failed to connect <owner>/<repo> to project. Make sure there aren't any typos and that you have access to the repository if it's private. このエラー文言は「リポジトリ名のtypo」や「アクセス権不足」を示唆するが、実際にはGitHub App自体が未インストールなだけのケースが多い（typoは無く、collaboratorsにも正しく載っている場合はこれを疑う）。

直し方（1回だけの人間操作で完結）

1. Vercelのプロジェクト設定 → Git（URL例: https://vercel.com/<team>/<project>/settings/git）を開く
2. 「Connect Git Repository」ボタンをクリック
3. GitHub側の同意画面（github.com/apps/vercel/installations/new/permissions?...）が開くので、「Only select repositories」で対象リポジトリを選択し「Install & Authorize」
4. Vercelの画面に自動で戻り、Git連携欄にリポジトリ名が表示されれば完了

この後、Claude/エージェント側で vercel git connect <repo-url> --yes を再実行すると > Connected が返る。検証: 実際に軽微なコミットをpushし、数十秒後に vercel ls で新しいdeploymentが自動的に Building → Ready になることを確認するまでが完了条件（「Connectedと表示された」だけでは自動デプロイが本当に動くかは分からない）。

根本原因2（別件だが同時に踏みやすい）: tsc --noEmit PASSはnext build成功を保証しない

Next.jsのnext buildはTypeScriptの型チェックとは別にESLintを実行する。@typescript-eslint/no-explicit-anyのようなルールは、型としては正しい（anyは合法な型）ためtsc --noEmitでは検出されず、next buildの段階で初めてFailed to compileとして落ちる。

特に、AIエージェント（Codex、あるいはCodexが使えず自動フォールバックした別のLLM実行系）に実装を委譲した直後は、型は通るがanyで誤魔化しているコードが混入しやすい。「typecheckが通ったので検証OK」と判断せず、デプロイ前に必ずnext build（または相当のlint込みビルド）まで一度実行する。

おまけ: Playwrightでrole=alertを使うときの罠

Next.jsはルート変更を支援技術に通知するため、自身で <div role="alert" aria-live="assertive" id="__next-route-announcer__"> をページに常に埋め込んでいる。アプリ独自のエラーメッセージの有無を page.getByRole('alert') で検証すると、このNext.js内部要素にもマッチしてfalse positiveになる（「エラーが出ていないはず」のテストが、実際には無関係な要素を拾って失敗する）。アプリ固有のエラー表示を検証したい場合は、page.getByText('実際のエラーメッセージ文言') のように具体的な文言で判定する方が安全。