Vercel 部署成功但首頁 404：先查 root route，不要急著重建專案

Vercel 的畫面顯示 deployment 是綠色，不代表網站每一個入口都已經存在。對 Next.js App Router 專案來說，npm run build 成功、Vercel 部署成功、首頁 / 真的回 200，是三件不同的事。

如果正式網域打開只看到 404，第一個反應不應該是重建整個專案或更換框架，而是先確認：這個專案是否真的有 root route？Vercel 部署的是不是正確分支與正確目錄？產出的 routes 裡面有沒有 /？

先把「部署成功」拆成三層

排查時可以把問題拆成三層，不要混在一起看：

1. Build 層： 原始碼能不能被 Next.js 編譯。
2. Deployment 層： Vercel 是否把這次 build 發布到某個 URL。
3. Route 層： 使用者打開的路徑是否真的有對應頁面。

首頁 404 通常卡在第三層。Vercel 可以成功部署一個沒有首頁 route 的專案；它只代表部署流程完成，不代表 / 一定存在。

App Router 專案先看 app/page.tsx

Next.js App Router 的首頁通常會落在：

app/page.tsx

如果專案只有 app/blog/page.tsx、app/[slug]/page.tsx 或其他子路由，卻沒有 app/page.tsx，那 /blog 或某篇文章可能能打開，但首頁 / 仍然會是 404。

最短的本機確認方式是先列出 route 相關檔案，再跑 production build：

npm run lint
npm run build

build output 裡若沒有看到 /，或 build 後用 production server 打 / 仍然是 404，就代表問題不是 Vercel 邊緣節點壞掉，而是 route 定義本身需要補齊。

不要只用 dev server 判斷

next dev 很適合開發，但正式站問題要盡量用 production mode 重現。至少跑一次：

npm run build
npm run start -- --hostname 127.0.0.1 --port 3000
curl -I http://127.0.0.1:3000/
curl -I http://127.0.0.1:3000/blog

如果本機 production mode 的 / 就是 404，問題在專案。若本機是 200，但 Vercel 正式網域是 404，再去查 Vercel 專案設定、Root Directory、分支、環境變數與最新 deployment 是否真的指到這份程式碼。

內容站還要順手查 /blog 與 sitemap

技術 Blog 或內容站不能只看首頁。首頁修好後，至少還要確認：

curl -I http://127.0.0.1:3000/blog
curl -I http://127.0.0.1:3000/sitemap.xml
curl -I http://127.0.0.1:3000/robots.txt

對 UCAMC 這類 Markdown 內容站，文章 canonical URL 是 root-level /{slug}，/blog 只是列表頁。因此一篇文章是否正常，應該檢查 /{slug}，而不是把新的 /blog/{slug} 404 當作錯誤。

這個 URL 策略也應該反映在 sitemap 與內部連結裡。若首頁、Blog 卡片、sitemap 使用不同 URL 形狀，搜尋引擎與讀者都會被帶到不一致的入口。

如果 Vercel 部署的是錯目錄

另一個常見誤判是 monorepo 或搬移專案後，Vercel 的 Root Directory 沒有指到 Next.js 專案所在資料夾。這時 build 可能看似成功，但部署出來的內容不是你以為的那個 app。

可檢查：

• Vercel Project Settings 的 Root Directory。
• GitHub 連結的 repository 與 branch。
• 最新 deployment 的 commit hash 是否等於你剛 push 的 commit。
• Build Command 是否仍是預期的 npm run build。
• Output 或 Framework Preset 是否被手動改過。

如果這些設定無法用目前權限確認，就不要猜測；把本機 production probe、Git commit hash 與正式網域 404 結果一起交給有 Vercel 權限的人處理。

一個比較安全的排查順序

遇到「部署成功但首頁 404」時，我會照這個順序縮小範圍：

1. 看 repo 裡是否有 app/page.tsx。
2. 跑 npm run lint 與 npm run build。
3. 用 npm run start 打本機 production /、/blog、代表性文章頁。
4. 確認 sitemap 是否包含首頁、Blog 與文章 canonical URL。
5. 比對 Vercel 最新 deployment 的 commit 與正式網域回應。
6. 若本機正常、正式站不正常，再把問題界定為部署設定或快取 freshness，而不是直接改程式。

這樣做的好處是，每一步都有可留下的證據。排查 404 最怕只用瀏覽器重新整理幾次就下結論；內容站長期維護更需要能交接的 status code、route、commit 與設定紀錄。

延伸整理

若問題發生在已上線的內容站，可以搭配 Vercel 部署回滾檢查表 判斷是否需要回復前一版；若是每日內容發布後要確認首頁、Blog、文章與 sitemap 都更新，則可接著看 Next.js 內容站上線後健康檢查模板。

重點不是把每次 404 都當成災難，而是先分清楚它屬於 route、設定、快取還是部署 freshness。分清楚層次後，修復通常會比想像中小得多。