Vercel Next.js API 路由超时配置：从 504 错误到生产级方案

主题: vercel-function-timeout-nextjs-api-route更新于: 2026/7/28作者：AgentFactory 技术团队

快速答案

核心结论：Vercel 上 Next.js API 路由超时由 maxDuration 控制，但受计划限制（Hobby 10s / Pro 60s / Enterprise 900s），无法完全禁用超时。
第一检查：确认当前 Vercel 计划（vercel billing）和路由运行时类型（export const runtime = 'nodejs'，避免 edge）。
最小修复命令：在项目根目录创建 vercel.json，写入 { "functions": { "app/api/**/*.js": { "maxDuration": 60 } } }，然后 vercel deploy --prod。
适用边界：仅适用于 Serverless Runtime（Node.js），Edge Runtime 超时更严格（15-60s）；超过 15 分钟的任务必须使用后台作业系统。

它解决什么问题

在 Vercel 上部署 Next.js 应用时，API 路由默认超时时间很短（Hobby 计划仅 10 秒）。当你需要处理以下场景时，默认超时会导致 504 Gateway Timeout 错误：

批量数据处理（如 CSV/Excel 导入导出）
大型文件分析或转换
慢速外部 API 调用（如第三方支付回调、邮件发送）
机器学习推理或图像/视频处理
数据库复杂查询（如聚合报表生成）

本文提供从诊断到配置的完整方案，涵盖所有 Vercel 计划，并包含生产环境的最佳实践。

核心配置：`vercel.json` 与 `maxDuration`

基础配置（适用于 App Router）

在项目根目录创建或编辑 vercel.json：

JSON
{
  "functions": {
    "app/api/**/*.js": {
      "maxDuration": 60,
      "runtime": "nodejs"
    }
  }
}

配置参数详解

参数	必填	说明	示例值
`maxDuration`	是	最大执行时间（秒），不能超过计划上限	`10`, `60`, `300`, `900`
`runtime`	否	运行时类型，默认 `nodejs`；避免使用 `edge`	`"nodejs"`

路径模式匹配规则

路由系统	正确路径模式	错误示例
App Router	`app/api/*/.js`	`api/*/.js`（缺少 `app/`）
Pages Router	`pages/api/*/.js`	`api/*/.js`（缺少 `pages/`）

关键：路径模式必须从项目根目录开始，包含 app/ 或 pages/ 前缀。如果配置不生效，首先检查路径模式是否匹配。

按路由粒度配置超时

JSON
{
  "functions": {
    "app/api/long-task.js": {
      "maxDuration": 300
    },
    "app/api/quick-task.js": {
      "maxDuration": 10
    }
  }
}

这样可以为不同路由设置不同的超时，避免全局延长导致成本增加。

与同类方案对比

方案	超时上限	运行时要求	成本影响	适用场景
`vercel.json` + `maxDuration`	900s (Enterprise)	Serverless (Node.js)	按执行时间计费	大多数 API 路由
Edge Runtime	15-60s	Edge	较低	低延迟、轻量请求
Vercel Cron Jobs	无限制（调度触发）	Serverless	按调用次数计费	定时后台任务
外部队列（BullMQ/SQS）	无限制	独立 Worker	额外基础设施成本	超长任务（>15min）

亮点：vercel.json 方案支持按路由粒度配置，无需修改代码，且与 Vercel 部署流程完全集成。

常见报错与排查

错误 1：504 Gateway Timeout

报错信息：504: GATEWAY_TIMEOUT 或 Function execution time exceeded

根因：API 路由执行时间超过 Vercel 计划限制。

解决步骤：

检查当前计划：vercel billing
升级计划（如需要）：vercel upgrade
在 vercel.json 中设置 maxDuration 为更高值
确保路由使用 Serverless Runtime（移除 export const runtime = 'edge'）

错误 2：vercel.json 配置不生效

报错信息：超时未延长，仍出现 504 错误

排查清单：

路径模式是否匹配路由系统（App Router vs Pages Router）
maxDuration 是否不超过计划上限
是否重新部署并检查部署日志：vercel logs
是否有多个 vercel.json 文件冲突

错误 3：Edge Runtime 超时限制

报错信息：即使配置 maxDuration，超时仍被限制在 15-60 秒

解决：在路由文件中移除或修改运行时声明：

TYPESCRIPT
// ❌ 错误：使用 Edge Runtime
export const runtime = 'edge';

// ✅ 正确：使用 Serverless Runtime
export const runtime = 'nodejs';
// 或直接移除该声明（默认即为 nodejs）

错误 4：函数执行成本过高

症状：Vercel 账单显著增加

优化策略：

使用 Vercel Analytics 监控函数执行时间
优化慢速查询（添加索引、使用缓存）
并行化外部 API 调用（Promise.all）
对于超长任务，迁移到后台作业系统

生产环境实践与注意事项

安全性建议

避免在超时配置中暴露敏感路径（如 /admin/**）
使用 Vercel Analytics 监控函数性能，设置告警
对超时失败添加重试逻辑和用户反馈（如返回 202 状态码，异步处理）

成本控制

JSON
{
  "functions": {
    "app/api/**/*.js": {
      "maxDuration": 60
    },
    "app/api/quick/**/*.js": {
      "maxDuration": 10
    }
  }
}

通过更具体的路径模式，只为需要长时间运行的路由设置高超时，其他路由保持默认。

超长任务处理（>15 分钟）

对于超过 15 分钟的任务，不要使用 API 路由。推荐方案：

Vercel Cron Jobs：定时调度，适合周期性任务
外部任务队列：BullMQ + Redis，或 AWS SQS + Lambda
后台 Worker：独立的 Node.js 服务，无超时限制

常见问题 FAQ

Q: 我可以在 Hobby 计划上使用 maxDuration: 60 吗？

A: 不可以。Hobby 计划的 Serverless 函数最大超时为 10 秒。如果设置 maxDuration: 60，Vercel 会忽略该配置并仍使用 10 秒限制。需要升级到 Pro 计划（60 秒）或 Enterprise 计划（最高 900 秒）才能使用更长的超时。

Q: 如何为单个 API 路由设置不同的超时？

A: 在 vercel.json 中使用更具体的路径模式。例如，为 pages/api/long-task.js 设置 60 秒超时：

JSON
{
  "functions": {
    "pages/api/long-task.js": {
      "maxDuration": 60
    }
  }
}

其他路由将使用默认超时（Hobby 10s，Pro 60s）。

Q: 如果我的任务需要超过 15 分钟，该怎么办？

A: Vercel Serverless 函数最大超时为 900 秒（15 分钟，Enterprise 计划）。对于更长的任务，建议使用 Vercel Cron Jobs 进行定时调度，或使用外部任务队列（如 BullMQ with Redis、AWS SQS）结合后台 worker 处理。避免在 API 路由中执行超长任务，以防止超时和成本问题。

Q: 配置后如何验证超时是否生效？

A: 部署后，在 API 路由中添加一个测试端点，使用 setTimeout 模拟长时间运行：

TYPESCRIPT
export async function GET() {
  await new Promise(resolve => setTimeout(resolve, 55000)); // 55 秒
  return Response.json({ status: 'ok' });
}

如果配置正确，该端点应在 55 秒后返回响应；如果 10 秒后返回 504，则配置未生效。

官方参考

Vercel 官方文档：Serverless Functions 超时处理