Next.js API路由本地正常但Vercel生产环境返回404问题排查

配置与问题现象 #

• API路由文件位于 /pages/api/shows.js，用于从数据库获取演出数据
• 前端请求URL写法：const apiUrl = ${process.env.NEXT_PUBLIC_API_LINK}/api/shows``
• 本地运行完全正常，可正确获取数据；部署到Vercel生产环境后，fetch请求返回404错误：

  Error fetching shows: Error: HTTP Error: 404
  

排查情况 #

• 已确认NEXT_PUBLIC_API_LINK在本地和生产环境的配置均正确
• 本地可通过http://localhost:3000/api/shows正常访问API路由
• Vercel上直接在浏览器打开https://example.com/api/shows能正常返回数据，但前端fetch请求却返回404

已尝试的解决步骤 #

• 直接浏览器访问Vercel上的API路由正常，但fetch请求失败
• 将API URL硬编码到fetch函数中，生产环境仍无法工作，排除环境变量问题
• 检查next.config.js和.env.local文件，未发现配置错误

相关代码（app/lib/fetchShows.ts） #

import { Show } from "@/app/lib/types";

export const fetchShows = async (): Promise<Show[]> => {
  const apiUrl = `${process.env.NEXT_PUBLIC_API_LINK}/api/shows`;
  console.log("Fetching from API:", apiUrl); // Debug log

  try {
    const response = await fetch(apiUrl);
    if (!response.ok) throw new Error(`HTTP Error: ${response.status}`);
    return response.json();
  } catch (error) {
    console.error("Error fetching shows:", error);
    return []; // 避免构建失败
  }
};

1. 文件路径大小写不匹配 #

Vercel部署环境对文件路径大小写敏感，但本地开发环境（如Windows）通常不敏感。如果你的API路由文件名和请求路径大小写不一致（比如文件名是Shows.js但请求路径是/api/shows），就会导致生产环境找不到路由。

修复：确保/pages/api下的文件名和前端请求路径的大小写完全一致，统一使用小写（比如shows.js对应/api/shows）。

2. Pages Router与App Router的请求逻辑差异 #

你的API路由属于Pages Router（位于/pages/api），但前端代码在App Router目录（app/lib）。如果fetchShows在Server Components中执行，使用完整域名的绝对URL会触发不必要的外部请求，可能遇到Vercel边缘网络的规则限制：

• Server Components中fetch默认是内部请求，无需完整域名，直接用相对路径/api/shows即可
• 即使是Client Components，使用相对路径也更可靠，避免环境变量配置失误

修复：修改fetch代码，改用相对路径：

export const fetchShows = async (): Promise<Show[]> => {
  const apiUrl = "/api/shows"; // 直接使用相对路径
  console.log("Fetching from API:", apiUrl);

  try {
    const response = await fetch(apiUrl);
    if (!response.ok) throw new Error(`HTTP Error: ${response.status}`);
    return response.json();
  } catch (error) {
    console.error("Error fetching shows:", error);
    return [];
  }
};

3. Vercel部署缓存未更新 #

Vercel的部署缓存可能导致旧的路由配置未被替换，新的API路由文件没有被正确识别。

修复：在Vercel控制台重新触发部署，勾选「清除构建缓存」选项，确保最新的路由文件被打包部署。

4. 边缘中间件拦截请求 #

如果项目使用了边缘中间件（middleware.js/middleware.ts），可能存在规则拦截了/api/shows的请求，导致请求无法到达API路由。

修复：

• 检查中间件代码，确认是否有阻止/api/shows路径的规则
• 查看Vercel的函数日志，确认API路由是否收到请求（若无日志记录，说明请求被拦截）
• 调整中间件规则，允许/api/shows路径的请求通过

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