如何调试本地正常但Vercel生产环境失效的环境变量（Sendgrid相关）

• 首先确认环境变量生效状态
  Vercel控制台新增/修改环境变量后，必须重新触发全量部署才会将变量注入到运行时，仅保存变量不重新部署不会生效。你可以在处理发件的服务端路由中增加临时日志，只打印API密钥的前10位避免泄露完整信息：
  console.log('SendGrid密钥前缀：', process.env.SENDGRID_API_KEY?.slice(0, 10))
  部署完成后提交一次表单请求，到Vercel控制台的「函数」日志面板查看打印的前缀，确认和你本地使用的密钥前缀一致，排除变量未正确注入的问题。
• 检查SendGrid账号权限配置
  如果你开启了SendGrid的IP访问白名单规则，Vercel服务端函数的运行IP是动态分配的，不在白名单内的请求会被直接拦截，需要暂时关闭IP白名单限制。另外确认你代码中使用的发件人邮箱已经在SendGrid后台完成了单sender验证，未验证的发件人在生产环境会被SendGrid直接拒收请求。
• 调整Vercel函数超时配置
  SendGrid的接口请求偶尔会出现延迟，Vercel免费版函数默认超时时间为10s，如果请求耗时超过阈值会被强制中断。你可以在项目根目录的vercel.json中增加函数超时配置（免费版最高支持10s）：

{
  "functions": {
    "app/api/**/*.{js,ts}": {
      "maxDuration": 10
    }
  }
}

如果你的发件路由在pages/api目录下，调整上面的路径匹配规则即可。

• 捕获完整错误信息定位问题
  在服务端调用SendGrid的逻辑外层增加try catch，捕获并打印完整错误信息到日志：

const sgMail = require('@sendgrid/mail')
sgMail.setApiKey(process.env.SENDGRID_API_KEY)

try {
  await sgMail.send({
    // 你的邮件配置
  })
} catch (err) {
  console.error('SendGrid请求错误：', err.response?.body || err.message)
  return NextResponse.json({ error: err.message }, { status: err.code || 500 })
}

根据日志中的错误码可以快速定位问题：401代表密钥无效，403代表权限/IP/发件人验证不通过，400代表请求参数格式错误。

• 确认环境变量文件忽略规则
  检查项目根目录的.gitignore是否已经包含*.local规则，避免env.local被不小心提交到代码仓库，Vercel会优先读取仓库内的环境变量文件，覆盖控制台配置的变量值。

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