Next.js部署后触发ERR_HTTP_HEADERS_SENT错误，求排查解决

错误本质 #

Error [ERR_HTTP_HEADERS_SENT] 是因为服务器在已向客户端发送响应后，又尝试再次发送响应，核心原因是API路由的异步逻辑或响应处理不规范。结合你本地正常、Vercel部署异常的场景，重点排查以下几点：

1. 异步逻辑未正确处理 #

Next.js API路由中，如果调用Google Sheets的异步操作未用await等待完成，或存在多次发送响应的分支，就会触发该错误。

错误示例（常见问题代码） #

// pages/api/submit.js
export default function handler(req, res) {
  if (req.method === 'POST') {
    // 异步操作未等待，导致后续代码提前执行
    writeToGoogleSheets(req.body)
      .then(() => res.status(200).json({ success: true }))
    // 此处意外重复发送响应
    res.status(400).json({ success: false })
  }
}

修复方案 #

用async/await处理异步操作，每个分支仅发送一次响应，并通过return终止后续代码执行：

// pages/api/submit.js
export default async function handler(req, res) {
  // 先校验请求方法，不符合直接返回
  if (req.method !== 'POST') {
    return res.status(405).json({ error: 'Method Not Allowed' })
  }

  try {
    // 等待Google Sheets写入完成
    await writeToGoogleSheets(req.body)
    return res.status(200).json({ success: true })
  } catch (err) {
    console.error('写入表格失败:', err)
    return res.status(500).json({ success: false, error: err.message })
  }
}

2. Vercel环境变量配置问题 #

本地正常但部署后失败，大概率是Vercel未正确配置Google Sheets的认证环境变量：

• 检查Vercel项目「Settings > Environment Variables」，确保所有本地用到的变量（如服务账号密钥、表格ID）都已配置，且名称完全一致；
• 确认Google Sheets已添加服务账号为编辑权限用户。

3. 未捕获异常导致重复响应 #

如果代码中存在未被捕获的异常，可能在错误处理前已发送部分响应，后续又触发错误响应。修复方式是用try/catch包裹所有异步操作，统一处理异常。

4. Vercel函数超时限制 #

Vercel无服务器函数默认超时时间较短（约10秒），若Google Sheets API调用耗时过长，会导致函数被强制终止，进而引发响应异常：

• 优化API调用逻辑，减少请求耗时；
• 若使用Vercel付费计划，可在项目设置中调整函数超时时间。

内容的提问来源于stack exchange，提问作者henoker