跳到主要内容

如何将 Next.js 用作前端的后端

Next.js 支持"前端后端"模式。这让你可以创建公共端点来处理 HTTP 请求并返回任何内容类型——不仅仅是 HTML。你还可以访问数据源并执行副作用，如更新远程数据。

如果你正在开始一个新项目，使用带有 --api 标志的 create-next-app 会自动在你的新项目的 app/ 文件夹中包含一个示例 route.ts，演示如何创建 API 端点。

Terminal
npx create-next-app@latest --api

注意：Next.js 后端功能不是完整的后端替代品。它们作为 API 层，具有以下特点：

  • 可以公开访问
  • 处理任何 HTTP 请求
  • 可以返回任何内容类型

要实现此模式，请使用：

公共端点​

路由处理器是公共 HTTP 端点。任何客户端都可以访问它们。

使用 route.ts 或 route.js 文件约定创建路由处理器：

/app/api/route.ts
export function GET(request: Request) {}

这处理发送到 /api 的 GET 请求。

对可能抛出异常的操作使用 try/catch 块：

/app/api/route.ts
import { submit } from '@/lib/submit'

export async function POST(request: Request) {
  try {
    await submit(request)
    return new Response(null, { status: 204 })
  } catch (reason) {
    const message =
      reason instanceof Error ? reason.message : '意外错误'

    return new Response(message, { status: 500 })
  }
}

避免在发送给客户端的错误消息中暴露敏感信息。

要限制访问，请实现身份验证和授权。请参阅身份验证。

内容类型​

路由处理器允许你提供非 UI 响应，包括 JSON、XML、图像、文件和纯文本。

Next.js 对常见端点使用文件约定：

你还可以定义自定义的端点，例如：

  • llms.txt
  • rss.xml
  • .well-known

例如，app/rss.xml/route.ts 为 rss.xml 创建路由处理器。

/app/rss.xml/route.ts
export async function GET(request: Request) {
  const rssResponse = await fetch(/* rss 端点 */)
  const rssData = await rssResponse.json()

  const rssFeed = `<?xml version="1.0" encoding="UTF-8" ?>
<rss version="2.0">
<channel>
 <title>${rssData.title}</title>
 <description>${rssData.description}</description>
 <link>${rssData.link}</link>
 <copyright>${rssData.copyright}</copyright>
 ${rssData.items.map((item) => {
   return `<item>
    <title>${item.title}</title>
    <description>${item.description}</description>
    <link>${item.link}</link>
    <pubDate>${item.publishDate}</pubDate>
    <guid isPermaLink="false">${item.guid}</guid>
 </item>`
 })}
</channel>
</rss>`

  const headers = new Headers({ 'content-type': 'application/xml' })

  return new Response(rssFeed, { headers })
}

对用于生成标记的任何输入进行清理。

消费请求负载​

使用 Request 实例方法，如 .json()、.formData() 或 .text() 来访问请求体。

GET 和 HEAD 请求不携带请求体。

/app/api/echo-body/route.ts
export async function POST(request: Request) {
  const res = await request.json()
  return Response.json({ res })
}

注意：在将数据传递给其他系统之前验证数据

/app/api/send-email/route.ts
import { sendMail, validateInputs } from '@/lib/email-transporter'

export async function POST(request: Request) {
  const formData = await request.formData()
  const email = formData.get('email')
  const contents = formData.get('contents')

  try {
    await validateInputs({ email, contents })
    const info = await sendMail({ email, contents })

    return Response.json({ messageId: info.messageId })
  } catch (reason) {
    const message =
      reason instanceof Error ? reason.message : '意外异常'

    return new Response(message, { status: 500 })
  }
}

你只能读取请求体一次。如果你需要再次读取它，请克隆请求：

/app/api/clone/route.ts
export async function POST(request: Request) {
  try {
    const clonedRequest = request.clone()

    await request.body()
    await clonedRequest.body()
    await request.body() // 抛出错误

    return new Response(null, { status: 204 })
  } catch {
    return new Response(null, { status: 500 })
  }
}

操作数据​

路由处理器可以转换、过滤和聚合来自一个或多个源的数据。这可以将逻辑从前端中移出，避免暴露内部系统。

你还可以将重计算卸载到服务器，减少客户端电池和数据使用。

/app/api/weather/route.ts
import { parseWeatherData } from '@/lib/weather'

export async function POST(request: Request) {
  const body = await request.json()
  const searchParams = new URLSearchParams({ lat: body.lat, lng: body.lng })

  try {
    const weatherResponse = await fetch(`${weatherEndpoint}?${searchParams}`)

    if (!weatherResponse.ok) {
      /* 处理错误 */
    }

    const weatherData = await weatherResponse.text()
    const payload = parseWeatherData.asJSON(weatherData)

    return new Response(payload, { status: 200 })
  } catch (reason) {
    const message =
      reason instanceof Error ? reason.message : '意外异常'

    return new Response(message, { status: 500 })
  }
}

注意：此示例使用 POST 来避免将地理位置数据放在 URL 中。GET 请求可能会被缓存或记录，这可能会暴露敏感信息。

代理到后端​

你可以使用路由处理器作为到另一个后端的代理。在转发请求之前添加验证逻辑。

/app/api/[...slug]/route.ts
import { isValidRequest } from '@/lib/utils'

export async function POST(request: Request, { params }) {
  const clonedRequest = request.clone()
  const isValid = await isValidRequest(clonedRequest)

  if (!isValid) {
    return new Response(null, { status: 400, statusText: 'Bad Request' })
  }

  const { slug } = await params
  const pathname = slug.join('/')
  const proxyURL = new URL(pathname, 'https://nextjs.org')
  const proxyRequest = new Request(proxyURL, request)

  try {
    return fetch(proxyRequest)
  } catch (reason) {
    const message =
      reason instanceof Error ? reason.message : '意外异常'

    return new Response(message, { status: 500 })
  }
}

或者使用：

NextRequest 和 NextResponse​

Next.js 扩展了 Request 和 Response Web API，提供了简化常见操作的方法。这些扩展在路由处理器和中间件中都可用。

两者都提供了读取和操作 cookie 的方法。

NextRequest 包含 nextUrl 属性，它暴露来自传入请求的解析值，例如，它使访问请求路径名和搜索参数变得更容易。

NextResponse 提供了 next()、json()、redirect() 和 rewrite() 等辅助方法。

你可以将 NextRequest 传递给任何期望 Request 的函数。同样，你可以在期望 Response 的地方返回 NextResponse。

/app/echo-pathname/route.ts
import { type NextRequest, NextResponse } from 'next/server'

export async function GET(request: NextRequest) {
  const nextUrl = request.nextUrl

  if (nextUrl.searchParams.get('redirect')) {
    return NextResponse.redirect(new URL('/', request.url))
  }

  if (nextUrl.searchParams.get('rewrite')) {
    return NextResponse.rewrite(new URL('/', request.url))
  }

  return NextResponse.json({ pathname: nextUrl.pathname })
}

了解更多关于 NextRequest 和 NextResponse 的信息。

Webhook 和回调 URL​

使用路由处理器接收来自第三方应用程序的事件通知。

例如，当 CMS 中的内容发生变化时重新验证路由。配置 CMS 在更改时调用特定端点。

/app/webhook/route.ts
import { type NextRequest, NextResponse } from 'next/server'

export async function GET(request: NextRequest) {
  const token = request.nextUrl.searchParams.get('token')

  if (token !== process.env.REVALIDATE_SECRET_TOKEN) {
    return NextResponse.json({ success: false }, { status: 401 })
  }

  const tag = request.nextUrl.searchParams.get('tag')

  if (!tag) {
    return NextResponse.json({ success: false }, { status: 400 })
  }

  revalidateTag(tag)

  return NextResponse.json({ success: true })
}

回调 URL 是另一个用例。当用户完成第三方流程时，第三方将他们发送到回调 URL。使用路由处理器来验证响应并决定将用户重定向到哪里。

/app/auth/callback/route.ts
import { type NextRequest, NextResponse } from 'next/server'

export async function GET(request: NextRequest) {
  const token = request.nextUrl.searchParams.get('session_token')
  const redirectUrl = request.nextUrl.searchParams.get('redirect_url')

  const response = NextResponse.redirect(new URL(redirectUrl, request.url))

  response.cookies.set({
    value: token,
    name: '_token',
    path: '/',
    secure: true,
    httpOnly: true,
    expires: undefined, // 会话 cookie
  })

  return response
}

重定向​

app/api/route.ts
import { redirect } from 'next/navigation'

export async function GET(request: Request) {
  redirect('https://nextjs.org/')
}

了解更多关于 redirect 和 permanentRedirect 中的重定向信息

中间件（Middleware）​

每个项目只允许一个中间件文件。使用 config.matcher 来定位特定路径。了解更多关于中间件的信息。

使用 middleware 在请求到达路由路径之前生成响应。

middleware.ts
import { isAuthenticated } from '@lib/auth'

export const config = {
  matcher: '/api/:function*',
}

export function middleware(request: Request) {
  if (!isAuthenticated(request)) {
    return Response.json(
      { success: false, message: '身份验证失败' },
      { status: 401 }
    )
  }
}

你还可以使用 middleware 代理请求：

middleware.ts
import { NextResponse } from 'next/server'

export function middleware(request: Request) {
  if (request.nextUrl.pathname === '/proxy-this-path') {
    const rewriteUrl = new URL('https://nextjs.org')
    return NextResponse.rewrite(rewriteUrl)
  }
}

middleware 可以产生的另一种响应是重定向：

middleware.ts
import { NextResponse } from 'next/server'

export function middleware(request: Request) {
  if (request.nextUrl.pathname === '/v1/docs') {
    request.nextUrl.pathname = '/v2/docs'
    return NextResponse.redirect(request.nextUrl)
  }
}

安全性​

速率限制​

你可以在 Next.js 后端中实现速率限制。除了基于代码的检查外，还要启用你的主机提供的任何速率限制功能。

/app/resource/route.ts
import { NextResponse } from 'next/server'
import { checkRateLimit } from '@/lib/rate-limit'

export async function POST(request: Request) {
  const { rateLimited } = await checkRateLimit(request)

  if (rateLimited) {
    return NextResponse.json({ error: '超出速率限制' }, { status: 429 })
  }

  return new Response(null, { status: 204 })
}

验证负载​

永远不要信任传入的请求数据。在使用之前验证内容类型和大小，并针对 XSS 进行清理。

使用超时来防止滥用和保护服务器资源。

将用户生成的静态资源存储在专用服务中。如果可能，从浏览器上传它们并将返回的 URI 存储在数据库中，以减少请求大小。

访问受保护资源​

在授予访问权限之前始终验证凭据。不要仅依赖中间件进行身份验证和授权。

从响应和后端日志中删除敏感或不必要的数据。

定期轮换凭据和 API 密钥。

预检请求​

预检请求使用 OPTIONS 方法来询问服务器是否允许基于源、方法和头的请求。

如果未定义 OPTIONS，Next.js 会自动添加它并根据其他定义的方法设置 Allow 头。

库模式​

社区库通常对路由处理器使用工厂模式。

/app/api/[...path]/route.ts
import { createHandler } from 'third-party-library'

const handler = createHandler({
  /* 库特定选项 */
})

export const GET = handler
// 或
export { handler as POST }

这为 GET 和 POST 请求创建共享处理器。库根据请求中的 method 和 pathname 自定义行为。

库还可以提供 middleware 工厂。

middleware.ts
import { createMiddleware } from 'third-party-library'

export default createMiddleware()

更多示例​

查看更多关于使用路由处理器和middleware API 参考的示例。

这些示例包括处理 Cookie、头、流式传输、中间件负匹配和其他有用的代码片段。

注意事项​

服务端组件​

在服务端组件中直接从其源获取数据，而不是通过路由处理器。

对于在构建时预渲染的服务端组件，使用路由处理器将使构建步骤失败。这是因为在构建时没有服务器监听这些请求。

对于按需渲染的服务端组件，从路由处理器获取数据会更慢，因为处理器和渲染过程之间存在额外的 HTTP 往返。

服务端 fetch 请求使用绝对 URL。这意味着到外部服务器的 HTTP 往返。在开发过程中，你自己的开发服务器充当外部服务器。在构建时没有服务器，在运行时，服务器通过你的公共域名可用。

服务端组件涵盖了大部分数据获取需求。但是，客户端数据获取可能对于以下情况是必要的：

  • 依赖于仅客户端 Web API 的数据：
    • 地理位置 API
    • 存储 API
    • 音频 API
    • 文件 API
  • 频繁轮询的数据

对于这些，使用社区库如 swr 或 react-query。

服务端操作​

服务端操作让你从客户端运行服务端代码。它们的主要目的是从前端客户端改变数据。

服务端操作是排队的。将它们用于数据获取会引入顺序执行。

export 模式​

export 模式输出没有运行时服务器的静态站点。需要 Next.js 运行时的功能不受支持，因为此模式产生静态站点，没有运行时服务器。

在 export 模式中，只支持 GET 路由处理器，结合 dynamic 路由段配置，设置为 'force-static'。

这可用于生成静态 HTML、JSON、TXT 或其他文件。

app/hello-world/route.ts
export const dynamic = 'force-static'

export function GET() {
  return new Response('Hello World', { status: 200 })
}

部署环境​

一些主机将路由处理器部署为 lambda 函数。这意味着：

  • 路由处理器无法在请求之间共享数据。
  • 环境可能不支持写入文件系统。
  • 长时间运行的处理器可能由于超时而终止。
  • WebSocket 不会工作，因为连接在超时后或在生成响应后关闭。
最后于 更新