Vercel 日誌排查:Runtime Logs、CLI 與 Log Drains
從 Vercel 執行階段日誌定位失敗的請求,使用 CLI 篩選,再設定 Log Drains 的 JSON 或 NDJSON 外送與簽章驗證。
剛發佈,正式環境就有一筆請求回傳 500。先到專案的 Logs 找出是哪次部署處理了這筆請求。如果部署根本沒成功,改查該次部署的 Build Logs。先弄清楚請求有沒有執行到函式,以及當時跑的是哪個版本,後面就知道該往哪裡查。
從 Runtime Logs 找到失敗的請求
先選環境和時間範圍,再用部署 ID 篩選。手上若有請求 ID,也可以把範圍縮到單筆。Vercel Functions 和 Routing Middleware 的執行記錄在 Logs 裡。懷疑請求被防火牆擋下時,也可以查 Firewall。如果請求由快取回應,可能不會產生新的函式日誌。Runtime Logs · 防火牆事件查詢
下面的指令會在已連結的專案中,查詢指定正式環境部署的執行階段錯誤。請把 dpl_example 換成實際的部署 ID。
vercel logs runtime --deployment dpl_example --environment production \
--since 30m --query 'level:error' --limit 50
這是 Vercel CLI v64 以上的寫法。level:error 篩選的是日誌等級。要查 HTTP 500,可用 vercel logs requests 的 httpStatus 條件找 CDN 請求記錄。加上 --json 時,日誌記錄在 .data 裡,最後一行則是查詢摘要,要分開處理。Vercel CLI 日誌指令
截至 2026 年 11 月 10 日,官方文件列出的 Runtime Logs 保留期為 Hobby 一小時、Pro 一天、Enterprise 三天。適用的專案啟用 Observability Plus 後可保留 30 天,每次最多選取連續 14 天。日誌若已超過保留期限,擴大查詢時段也找不回來。Observability Plus
讓下一次錯誤有欄位可查
如果日誌只留「結帳失敗」,出錯時還是得逐行找線索。可以從 event 和 outcome 這類跨版本含義穩定的欄位開始。這個 Next.js App Router 的測試用 Route Handler 只輸出一行 JSON,不會讀取客戶資料。Next.js Route Handlers
export async function POST() {
console.log(JSON.stringify({
event: "checkout_probe",
outcome: "ok",
}));
return Response.json({ ok: true });
}
這行 JSON 外送後可能是 message 裡的字串。接收時可以解析,並和 Vercel 的 level、HTTP 狀態碼分開存放。例如 console.error 的輸出會記為 error 等級。權杖、個人資料和請求本文都不宜寫入這類事件。Log Drain 記錄格式
先選一個專案設定 Log Drain
Log Drains 支援 Pro 與 Enterprise,Pro Trial 不適用。用具備團隊設定權限的帳號,開啟 Team Settings → Drains,新增 Log 並選擇 Custom Endpoint。先選要查的專案、環境和日誌來源,格式可用整批 JSON 陣列,或每行一個物件的 NDJSON。沒設取樣規則時,會轉送所選範圍內的日誌。若有規則,以第一條符合的規則為準,沒有符合的請求不會轉送。Vercel Drains · 設定 Drain
Vercel 透過 HTTPS POST 傳送。接收端要在解析或轉換前,用原始本文位元組驗證 x-vercel-signature。下面的 Node.js 函式接收本文 Buffer 和標頭值,密鑰從伺服器端設定讀取。
import { createHmac, timingSafeEqual } from "node:crypto";
export function validDrainSignature(rawBody, signature, secret) {
if (!Buffer.isBuffer(rawBody) ||
typeof signature !== "string" || !/^[0-9a-f]{40}$/i.test(signature) ||
typeof secret !== "string" || !secret.length) {
return false;
}
const expected = createHmac("sha1", secret).update(rawBody).digest();
return timingSafeEqual(expected, Buffer.from(signature, "hex"));
}
請限制請求大小。驗證簽章後,拒絕格式錯誤的批次或其中不是 JSON 物件的項目。確定整批資料已可靠接收後再回傳 HTTP 200。也可以用 Custom Headers 加一層驗證。管理介面會顯示傳送失敗,但目前官方文件沒有承諾固定的重試時程,也沒有保證補送歷史日誌。可監控接收缺口,並用專案 ID 加上記錄 ID 防止重複寫入。Drain 接收安全 · 查看傳送錯誤
到接收端確認實際存下的欄位
執行 Drain 的 Test 後,在選定的環境產生一筆新日誌,再到接收端依部署 ID 查找。確認 timestamp 以 Unix 時間起點的毫秒數解析,並能分別篩選選填的數值欄位 statusCode 和日誌等級 level。建置日誌可能沒有 requestId。頂層 statusCode 的 -1 代表 Lambda 異常終止而未回應,proxy.statusCode 的 -1 則表示 ISR 在背景重新驗證。兩者都要與實際 HTTP 狀態碼分開。Log Drain 記錄格式
接到觀測雲時,DataKit 的 Log Streaming 採集器提供 /v1/write/logstreaming。先核對接收格式和驗證需求。有格式轉換需求時,可在 HTTPS 接收端先驗證簽章,把事件整理後再送往 DataKit。在日誌檢視器依部署 ID 篩選,同一次發佈的錯誤事件和回應狀態就能一起查。觀測雲 Log Streaming(簡中) · 觀測雲日誌檢視器(簡中)
