API 路由

示例

• 基本 API 路由
• 具有中间件的 API 路由
• 支持 GraphQL 的 API 路由
• REST 模式的 API 路由
• 支持 CORS 的 API 路由

API 路由为使用 Next.js 构建你自己的 API 提供了一种解决方案。

pages/api 目录下的任何文件都将作为 API 端点映射到 /api/*，而不是 page。这些文件只会增加服务端文件包的体积，而不会增加客户端文件包的大小。

例如，以下 API 路由 pages/api/user.js 返回 json 格式的数据，并且状态码为 200：

export default function handler(req, res) {
  res.status(200).json({ name: 'John Doe' })
}

为了使 API 路由能正常工作，你需要导出（export）一个默认函数（即 请求处理器），并且该函数能够接收以下参数：

• req: 一个 http.IncomingMessage 实例，以及一些 预先构建的中间件
• res: 一个 http.ServerResponse 实例，以及一些 辅助函数

要处理 API 路由的不同 HTTP 方法，可以在请求处理器中使用 req.method，如下所示：

export default function handler(req, res) {
  if (req.method === 'POST') {
    // Process a POST request
  } else {
    // Handle any other HTTP method
  }
}

要用 fetch 函数请求 API 端点，请查看本章开头列出的任何一个示例。

Use Cases

For new projects, you can build your entire API with API Routes. If you have an existing API, you do not need to forward calls to the API through an API Route. Some other use cases for API Routes are:

• Masking the URL of an external service (e.g. /api/secret instead of https://company.com/secret-url)
• Using Environment Variables on the server to securely access external services.

注意事项

• API 路由 未指定 CORS 标头意味着它们在默认情况下 仅是同源（same-origin）策略。你可以通过使用 cors 中间件 包装出一个请求处理器来自定义此行为。
• API路由不能与 next export 一起使用

相关内容

接下来，建议学习以下章节：