Netlify部署NextJS函数报错：Cannot read properties of undefined (reading 'headers')

针对你遇到的本地运行正常、生产环境报错的问题，以下是核心原因分析和修复方案：

1. 混淆Netlify Functions的Handler参数 #

Netlify Functions的handler函数接收的参数是(event, context)，而非Express框架的(req, res)。如果你的代码错误地用req作为第一个参数，生产环境中会因为参数结构不匹配，导致访问req.headers时触发undefined错误。

修复示例：

// 正确的Handler结构
exports.handler = async (event, context) => {
  // 从event中获取请求headers
  const incomingHeaders = event.headers;
  
  try {
    // 第一步：从源API拉取数据
    const sourceRes = await fetch('https://你的源API地址', {
      headers: {
        // 只传递必要的headers，比如授权、内容类型
        'Authorization': incomingHeaders['authorization'],
        'Content-Type': 'application/json'
      }
    });

    // 检查源API响应状态
    if (!sourceRes.ok) {
      throw new Error(`源API请求失败: ${sourceRes.status}`);
    }

    const sourceData = await sourceRes.json();

    // 第二步：转发数据到目标API
    const forwardRes = await fetch('https://你的目标API地址', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json'
        // 按需添加其他必要headers
      },
      body: JSON.stringify(sourceData)
    });

    // 检查转发请求状态
    if (!forwardRes.ok) {
      throw new Error(`转发请求失败: ${forwardRes.status}`);
    }

    const forwardData = await forwardRes.json();

    return {
      statusCode: 200,
      body: JSON.stringify(forwardData)
    };
  } catch (error) {
    // 强制捕获所有错误，避免未处理的Promise拒绝
    return {
      statusCode: 500,
      body: JSON.stringify({ error: error.message })
    };
  }
};

2. 未捕获异步操作的错误 #

本地netlify-cli对未处理的Promise拒绝容错性较高，但生产环境会严格抛出Runtime.UnhandledPromiseRejection错误。如果你的代码没有用try/catch包裹所有异步操作（fetch、await），一旦请求失败就会触发该错误。

修复要点：

• 所有await操作必须放在try代码块内
• 在catch块中返回明确的错误响应，确保Promise始终被处理

3. 错误访问响应对象的headers #

如果代码假设fetch返回的响应一定存在，但网络错误场景下fetch会直接reject，导致后续代码尝试访问undefined的headers属性。此外，即使fetch返回HTTP响应，也需要先通过response.ok确认请求成功，再读取响应内容或headers。

错误写法示例：

// 未检查响应状态，可能触发错误
const res = await fetch('https://api.example.com');
const headers = res.headers;

正确写法示例：

try {
  const res = await fetch('https://api.example.com');
  if (!res.ok) {
    throw new Error(`HTTP错误: ${res.status}`);
  }
  const headers = res.headers;
  // 后续处理逻辑
} catch (err) {
  // 捕获并处理错误
}

4. 生产环境Headers传递问题 #

生产环境中，Netlify会过滤或修改部分系统headers（如host、connection），如果直接传递所有event.headers到目标API，可能引发异常。建议只手动传递必要的业务headers，而非全部转发。

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