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(簡中) · 觀測雲日誌檢視器(簡中)

下一篇 · Google Cloud Logging · 延伸閱讀 · AWS Lambda 日誌(簡中)

取得專屬方案

聯絡我們

加入社群

微信扫码
加入官方交流群

立即體驗

在线开通,按量计费,真正的云服务!

立即開始

选择观测云版本

代码托管平台