Netlify部署的Next.js所有API路由返回502错误求助

问题描述 #

Netlify部署Next.js应用后，客户端访问任意API路由均返回502 Bad Gateway错误，本地运行则完全正常。控制台错误信息：

GET https://example.com/api/testApi 502

已排查代码、环境变量及Netlify配置，问题覆盖所有API路由，并非单个路由异常。已知配置细节：Netlify环境变量设置正确，本地开发环境可正常访问API路由。

相关代码与配置 #

API路由代码（pages/api/testApi.js） #

// pages/api/testApi.js
exports.handler = async (event, context) => {
    const response = {
      statusCode: 200,
      headers: {
        "Access-Control-Allow-Origin": "*",
        "Access-Control-Allow-Headers": "Content-Type",
        "Access-Control-Allow-Methods": "GET, POST, OPTION",
      },
      body: JSON.stringify({ message: "Hello World" })
    };
    return response;
  };

前端组件代码（components/TestButton.js） #

// components/TestButton.js
import { useState } from 'react';

const TestButton = () => {
  const [message, setMessage] = useState('');

  const testApi = async () => {
    try {
      const response = await fetch('/api/testApi');
      const data = await response.json();
      setMessage(data.message);
    } catch (error) {
      setMessage('An error occurred.');
    }
  };

  return (
    <div>
      <button onClick={testApi}>Test API</button>
      <p>{message}</p>
    </div>
  );
};

export default TestButton;

Netlify配置文件（netlify.toml） #

[build]
  command = "next build"
  publish = ".next"

[[plugins]]
  package = "@netlify/plugin-nextjs"

[functions]
  included_files = [".next/*.json"]

排查与解决建议 #

• 修正API路由导出方式：Next.js Pages Router的API路由需使用export default而非Netlify Functions的exports.handler写法。同时注意Access-Control-Allow-Methods中的OPTIONS拼写（原代码写为OPTION少了S），修改后的API代码：

  // pages/api/testApi.js
  export default async function handler(req, res) {
    res.setHeader("Access-Control-Allow-Origin", "*");
    res.setHeader("Access-Control-Allow-Headers", "Content-Type");
    res.setHeader("Access-Control-Allow-Methods", "GET, POST, OPTIONS");
    res.status(200).json({ message: "Hello World" });
  }
  

• 移除冗余的Functions配置：@netlify/plugin-nextjs会自动处理Next.js API路由，无需手动配置[functions]区块，删除后netlify.toml内容如下：

  [build]
    command = "next build"
    publish = ".next"
  
  [[plugins]]
    package = "@netlify/plugin-nextjs"
  

• 检查插件与Next.js版本兼容性：确保@netlify/plugin-nextjs版本适配当前Next.js版本，尝试更新到最新版：

  npm install @netlify/plugin-nextjs@latest
  

• 查看Netlify函数日志：在Netlify控制台的「Functions」→「Logs」中查看函数执行的具体错误信息，502通常源于函数执行失败（如语法错误、依赖缺失），日志会给出明确提示。

• 确认环境变量作用域：确保API路由所需的环境变量设置为「Runtime」作用域（勾选Deploy site-wide），仅Build作用域的变量无法在运行时被函数读取。

• 验证本地构建完整性：本地重新执行next build，确认构建过程无报错，.next目录生成正常后再重新部署。

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