Vercel Serverless API 调用失败的常见原因与修复指南-html教程-PHP中文网

Vercel Serverless API 调用失败的常见原因与修复指南

本文详解 Vercel 静态站点中客户端调用 /api 路由返回 404 的根本原因，涵盖路径配置、文件结构、部署验证及调试方法，并提供可直接运行的修复代码。

本文详解 vercel 静态站点中客户端调用 `/api` 路由返回 404 的根本原因，涵盖路径配置、文件结构、部署验证及调试方法，并提供可直接运行的修复代码。

在 Vercel 上部署静态网站（如 HTML + Tailwind CSS + Vanilla JS）时，通过 fetch("/api/form") 调用 Serverless Function 却持续报 404 Not Found，是开发者高频遇到的问题。表面上看路径 /api/form 与文件结构一致，但实际失败往往源于项目结构、构建输出路径或部署配置的隐性不匹配，而非 fetch 地址本身错误——答案中“保持 /api/form 不变”看似矛盾，实则揭示了一个关键前提：该路径仅在满足特定项目结构和部署约定时才有效。

✅ 正确的项目结构是前提

Vercel 自动将 api/ 目录下的文件映射为 Serverless Functions，但前提是：

api/ 文件夹必须位于项目根目录下（即与 package.json 或 vercel.json 同级）；
函数文件路径需严格对应路由：api/form.js → 可访问 /api/form；
若使用 dist/ 作为构建输出目录（如你提到的 /dist/index.js），api/ 文件夹绝不能放在 dist/ 内——它属于源码层，需与构建产物并列于根目录：

your-project/
├── api/
│   └── form.js          ← 正确：根目录下的 api 文件夹
├── dist/
│   ├── index.html
│   └── index.js         ← 客户端代码在此，fetch("/api/form") 才能命中
├── package.json
└── vercel.json (可选)

❌ 错误示例：dist/api/form.js 或 src/api/form.js（未正确复制到根目录）均会导致 404。

? 客户端调用：路径无需修改，但需确保上下文正确

你的 fetch("/api/form") 写法本身完全正确——这是相对路径，由浏览器基于当前页面 URL 解析。假设部署后访问地址为 https://your-domain.vercel.app/，则请求会自动指向 https://your-domain.vercel.app/api/form。
但若页面部署在子路径（如 https://your-domain.vercel.app/sub/），而 index.html 在 sub/ 下，则 /api/form 仍会解析为 https://your-domain.vercel.app/api/form（因 / 表示根域），这通常是期望行为。

✅ 推荐写法（显式且健壮）：

CAPTURELAB

一款面向游戏玩家的AI游戏视频工具，可以自动识别和整理游戏精彩片段，帮助玩家更快制作游戏集锦视频。

下载

// /dist/index.js 中保持原样，无需改为绝对 URL
const response = await fetch("/api/form", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify(formData),
});

?️ 必须验证的三大部署环节

检查 Vercel 项目根目录
登录 Vercel Dashboard，进入项目 → Settings → Git → 确认 Root Directory 设置为 .（而非 dist 或 src）。若误设为 dist，Vercel 将忽略根目录下的 api/ 文件夹。
查看 Vercel 构建日志
在部署日志中搜索 api/ 关键字，确认类似输出：
Detected 1 Serverless Function in api/
若无此提示，说明 api/ 未被识别——大概率是位置错误或文件扩展名不符（Vercel 支持 .js, .ts, .go, .py，但 .mjs 或 .cjs 需额外配置）。
利用浏览器 Network 面板精准诊断
- 打开 DevTools → Network → 触发表单提交；
- 找到 /api/form 请求 → 查看 Status 和 Preview/Response；
- 若状态为 404 且响应为空，说明请求根本未到达函数（结构/部署问题）；
- 若状态为 500 或有错误文本，则函数已执行，问题在逻辑层（如 req.body 解析失败）。

? 进阶：处理 req.body 的兼容性问题

你的函数中 req.body 直接使用存在风险——Vercel 的 Node.js Runtime 默认不会自动解析 JSON body。需手动解析或启用中间件：

// api/form.js（修复版）
module.exports = async (req, res) => {
  try {
    // ✅ 显式解析 JSON body
    let data;
    if (req.method === "POST") {
      const rawBody = await new Promise((resolve) => {
        let body = "";
        req.on("data", (chunk) => (body += chunk));
        req.on("end", () => resolve(body));
      });
      data = JSON.parse(rawBody);
    }

    console.log("Received form data:", data);
    res.status(200).json({ success: true, received: data });

  } catch (error) {
    console.error("Error processing request:", error);
    res.status(500).json({ error: "Internal Server Error" });
  }
};