Vercel 日志实战：运行时日志、Log Drains 与 Serverless 排障

Vercel 作为 Serverless/Edge 部署平台，其日志体系围绕"构建 + 运行时"两条线展开，且受 Serverless 特性影响（冷启动、实例易失），日志外送几乎是刚需。本文讲清 Vercel 日志的查看、外送与结构化实践，并给出观测云平台落地方案。

核心要点速览

• 两类日志：构建日志（Build Logs，部署过程）与运行时日志（Runtime Logs，函数执行）。
• 运行时日志保留有限：免费/低档套餐保留期短，长期留存与分析必须配置 Log Drains 外送。
• Log Drains 需要 Pro/Enterprise 套餐：以 NDJSON 格式批量 POST 到自定义端点。
• 结构化 JSON 输出是 Serverless 日志的硬要求：实例转瞬即逝，日志必须即产即走、平台可查。

1. Vercel 的日志类型

运行时日志里每条函数日志自动附带：时间戳、请求 ID、函数名、部署 ID、区域。按请求 ID 过滤即可还原单次调用的全部输出。

2. Serverless 函数的日志写法

// Next.js API Route / Serverless Function
export async function POST(req) {
  const body = await req.json();
  console.log(JSON.stringify({
    level: "info",
    msg: "订单创建",
    order_id: body.orderId,
    ts: new Date().toISOString(),
  }));
  ...
}

要点：JSON 单行输出（多行会被拆散）、必带业务 ID（order_id/user_id）、正确分级（console.error 进错误级别）。Edge Runtime 用法相同（受限于 Edge API 子集）。

3. Log Drains：外送到日志平台

Vercel Dashboard → Team Settings → Log Drains → Add Log Drain：

1. 选 Custom Log Drain；
2. 选择项目与日志源（Functions/Builds/Edge Requests/Firewall）；
3. 传输格式选 NDJSON（每行一个 JSON 对象，平台友好）；
4. Endpoint 填日志平台的 HTTP 接收地址；
5. Custom Headers 加 Authorization: Bearer <token> 做鉴权；
6. 保存后用 Test Log Drain 发送样例验证。

注意：Log Drains 需要 Pro 或 Enterprise 套餐。

验证外送日志是否正确入库

接入前先用 Test Log Drain 样本核对接收端协议。观测云 DataKit 的 HTTP 日志接收提供 logstreaming 接口；若 Vercel 的验证握手、批量格式或鉴权方式与接口要求不同，需由接收服务完成适配，不能只换一个 URL。

适配后保留项目、部署版本及请求标识，按实际字段解析时间与日志级别；HTTP 状态码单独存放。先核对一条已知函数错误及其堆栈，再在日志查看器按部署版本查找同类失败，避免把不同发布批次混在一起。

常见问题（FAQ）

免费版 Vercel 日志保留多久？

Hobby 套餐运行时日志保留很短（小时级滚动窗口），且不支持 Log Drains。生产项目升级 Pro 并配置外送是标配动作。

Edge 函数和 Serverless 函数日志有区别吗？

两者都进运行时日志，字段结构一致；区别在运行时能力（Edge 是受限 API 子集）。日志写法与接入方式相同。

为什么我的 console.log 在 Vercel 日志里看不到？

常见原因：函数该次调用根本没执行（缓存命中/静态化）、部署版本不对、日志面板过滤条件过严。用请求 ID 精确过滤定位。

Log Drain 推送给平台失败会重试吗？

Vercel 对失败批次有有限重试，但长期不可达会丢失。接收端需记录失败批次并核对重试结果；缓存不能保证长期故障期间不丢数据。

系列阅读

• 上一篇：Heroku 日志实战
• 下一篇：GCP 日志实战
• 相关阅读：AWS Lambda 日志实战 ｜ 微服务日志最佳实践

---