NNext.js 中文网 GitHub

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

了解如何将 Next.js 用作后端框架

Next.js 支持“前端的后端(Backend for Frontend)”模式。这使你可以创建公共端点来处理 HTTP 请求并返回任何内容类型——而不仅仅是 HTML。你还可以访问数据源并执行更新远程数据等副作用。

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

bash · pnpm
pnpm create next-app --api
bash · npm
npx create-next-app@latest --api
bash · yarn
yarn create next-app --api
bash · bun
bun create next-app --api

小知识:Next.js 的后端能力并非完整后端的替代品。它们充当 API 层,具备以下特点:

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

要实现此模式,请使用:

公共端点#

Route Handler 是公共 HTTP 端点。任何客户端都可以访问它们。

使用 route.ts 或 route.js 文件约定创建 Route Handler:

/app/api/route.ts
export function GET(request: Request) {}
/app/api/route.js
export function GET(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 : 'Unexpected error'

    return new Response(message, { status: 500 })
  }
}
/app/api/route.js
import { submit } from '@/lib/submit'

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

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

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

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

内容类型#

Route Handler 使你能够提供非 UI 响应,包括 JSON、XML、图像、文件和纯文本。

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

你还可以定义自定义的端点,例如:

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

例如,app/rss.xml/route.ts 会为 rss.xml 创建一个 Route Handler。

/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 })
}
/app/rss.xml/route.js
export async function GET(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 })
}

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

内容协商#

你可以使用带有请求头匹配的 rewrites 来根据请求的 Accept 头从同一 URL 提供不同的内容类型。这被称为内容协商。

例如,一个文档站点可能会从相同的 /docs/… URL 向浏览器提供 HTML 页面,向 AI 代理提供原始 Markdown。

1. 配置一个匹配 Accept 头的 rewrite:

next.config.js
module.exports = {
  async rewrites() {
    return [
      {
        source: '/docs/:slug*',
        destination: '/docs/md/:slug*',
        has: [
          {
            type: 'header',
            key: 'accept',
            value: '(.*)text/markdown(.*)',
          },
        ],
      },
    ]
  },
}

当对 /docs/getting-started 的请求包含 Accept: text/markdown 时,rewrite 会将其路由到 /docs/md/getting-started。该路径上的 Route Handler 会返回 Markdown 响应。未在 Accept 头中发送 text/markdown 的客户端将继续接收普通的 HTML 页面。

2. 为 Markdown 响应创建一个 Route Handler:

app/docs/md/[...slug]/route.ts
import { getDocsMd, generateDocsStaticParams } from '@/lib/docs'

export async function generateStaticParams() {
  return generateDocsStaticParams()
}

export async function GET(_: Request, ctx: RouteContext<'/docs/md/[...slug]'>) {
  const { slug } = await ctx.params
  const mdDoc = await getDocsMd({ slug })

  if (mdDoc == null) {
    return new Response(null, { status: 404 })
  }

  return new Response(mdDoc, {
    headers: {
      'Content-Type': 'text/markdown; charset=utf-8',
      Vary: 'Accept',
    },
  })
}
app/docs/md/[...slug]/route.js
import { getDocsMd, generateDocsStaticParams } from '@/lib/docs'

export async function generateStaticParams() {
  return generateDocsStaticParams()
}

export async function GET(_, { params }) {
  const { slug } = await params
  const mdDoc = await getDocsMd({ slug })

  if (mdDoc == null) {
    return new Response(null, { status: 404 })
  }

  return new Response(mdDoc, {
    headers: {
      'Content-Type': 'text/markdown; charset=utf-8',
      Vary: 'Accept',
    },
  })
}

Vary: Accept 响应头告诉缓存,响应正文取决于 Accept 请求头。没有它,共享缓存可能会向浏览器提供缓存的 Markdown 响应(反之亦然)。大多数托管提供商已经将 Accept 头纳入其缓存键,但显式设置 Vary 可确保在所有 CDN 和代理缓存中的正确行为。

generateStaticParams 使你能够在构建时预渲染 Markdown 变体,这样它们就可以从边缘提供,而无需在每次请求时都访问源服务器。

3. 使用 curl 测试:

bash
# 返回 Markdown
curl -H "Accept: text/markdown" https://example.com/docs/getting-started

# 返回普通的 HTML 页面
curl https://example.com/docs/getting-started

小知识:

  • 即使不使用 rewrite,/docs/md/... 路由仍可直接访问。如果你想限制它仅通过 rewrite 提供服务,请使用 proxy 来阻止不包含预期 Accept 头的直接请求。
  • 对于更高级的协商逻辑,你可以使用 proxy 代替 rewrite,以获得更大的灵活性。

使用请求负载#

使用 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/echo-body/route.js
export async function POST(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 : 'Unexpected exception'

    return new Response(message, { status: 500 })
  }
}
/app/api/send-email/route.js
import { sendMail, validateInputs } from '@/lib/email-transporter'

export async function POST(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 : 'Unexpected exception'

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

请求正文只能读取一次。如果需要再次读取,请克隆请求:

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

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

    return new Response(null, { status: 204 })
  } catch {
    return new Response(null, { status: 500 })
  }
}
/app/api/clone/route.js
export async function POST(request) {
  try {
    const clonedRequest = request.clone()

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

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

处理数据#

Route Handler 可以转换、过滤和聚合来自一个或多个数据源的数据。这使逻辑远离前端,并避免暴露内部系统。

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

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 : 'Unexpected exception'

    return new Response(message, { status: 500 })
  }
}
js
import { parseWeatherData } from '@/lib/weather'

export async function POST(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 : 'Unexpected exception'

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

小知识:此示例使用 POST 以避免将地理位置数据放入 URL。GET 请求可能会被缓存或记录,从而暴露敏感信息。

代理到后端#

要将请求转发到另一个后端,请在 next.config.js 中使用 rewrites 或使用 proxy rewrite。当您需要验证请求、向后端进行身份验证或转换其响应时,请使用 Route Handler。

仅向后端发送其所需的请求头和凭据。复制每个传入的请求头也会转发用户的 Cookie 和 Authorization 值。如果附加凭据,请确保请求无法到达其他服务器。

此 Route Handler 公开一组固定的后端端点,验证传入的 JSON 请求,使用服务器端令牌调用后端,并在返回之前转换响应。由于上游路径来自 ENDPOINTS 映射而非请求 URL,调用者无法将请求或其令牌指向其他目标。

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

const BACKEND_ORIGIN = 'https://api.example.com'

const ENDPOINTS = new Map([
  ['checkout', '/v1/checkout'],
  ['orders/preview', '/v1/orders/preview'],
])

export async function POST(request: Request, { params }) {
  const { slug } = await params
  const path = ENDPOINTS.get(slug.join('/'))

  if (!path) {
    return new Response(null, { status: 404, statusText: 'Not Found' })
  }

  const isValid = await isValidRequest(request.clone())

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

  try {
    const upstream = await fetch(new URL(path, BACKEND_ORIGIN), {
      method: 'POST',
      redirect: 'error',
      headers: {
        'Content-Type': 'application/json',
        Authorization: `Bearer ${process.env.API_TOKEN}`,
      },
      body: await request.text(),
    })

    if (!upstream.ok) {
      return Response.json(
        { error: 'Upstream request failed' },
        { status: 502 }
      )
    }

    const data = await upstream.json()

    return Response.json({ ...data, source: 'proxied-through-nextjs' })
  } catch {
    return Response.json({ error: 'Bad Gateway' }, { status: 502 })
  }
}
/app/api/[...slug]/route.js
import { isValidRequest } from '@/lib/utils'

const BACKEND_ORIGIN = 'https://api.example.com'

const ENDPOINTS = new Map([
  ['checkout', '/v1/checkout'],
  ['orders/preview', '/v1/orders/preview'],
])

export async function POST(request, { params }) {
  const { slug } = await params
  const path = ENDPOINTS.get(slug.join('/'))

  if (!path) {
    return new Response(null, { status: 404, statusText: 'Not Found' })
  }

  const isValid = await isValidRequest(request.clone())

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

  try {
    const upstream = await fetch(new URL(path, BACKEND_ORIGIN), {
      method: 'POST',
      redirect: 'error',
      headers: {
        'Content-Type': 'application/json',
        Authorization: `Bearer ${process.env.API_TOKEN}`,
      },
      body: await request.text(),
    })

    if (!upstream.ok) {
      return Response.json(
        { error: 'Upstream request failed' },
        { status: 502 }
      )
    }

    const data = await upstream.json()

    return Response.json({ ...data, source: 'proxied-through-nextjs' })
  } catch {
    return Response.json({ error: 'Bad Gateway' }, { status: 502 })
  }
}

小知识:此示例将整个请求和上游响应读入内存。对于大型负载或流式响应,请改用 rewrite。

NextRequest 和 NextResponse#

Next.js 通过简化常见操作的方法扩展了 Request 和 Response Web API。这些扩展在 Route Handler 和 Proxy 中均可用。

两者都提供了读取和操作 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 })
}
/app/echo-pathname/route.js
import { NextResponse } from 'next/server'

export async function GET(request) {
  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#

使用 Route Handler 接收来自第三方应用程序的事件通知。

例如,当 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, 'max')

  return NextResponse.json({ success: true })
}
/app/webhook/route.js
import { NextResponse } from 'next/server'

export async function GET(request) {
  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, 'max')

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

回调 URL 是另一个用例。当用户完成第三方流程后,第三方会将其发送到回调 URL。使用 Route Handler 验证响应并决定将用户重定向到何处。

/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 destination = new URL(redirectUrl ?? '/', request.url)
  // 防止开放重定向:仅允许同源目标
  if (destination.origin !== request.nextUrl.origin) {
    return new Response('Invalid redirect', { status: 400 })
  }

  const response = NextResponse.redirect(destination)

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

  return response
}
/app/auth/callback/route.js
import { NextResponse } from 'next/server'

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

  const destination = new URL(redirectUrl ?? '/', request.url)
  // 防止开放重定向:仅允许同源目标
  if (destination.origin !== request.nextUrl.origin) {
    return new Response('Invalid redirect', { status: 400 })
  }

  const response = NextResponse.redirect(destination)

  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/')
}
app/api/route.js
import { redirect } from 'next/navigation'

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

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

Proxy#

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

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

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

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

export function proxy(request: Request) {
  if (!isAuthenticated(request)) {
    return Response.json(
      { success: false, message: 'authentication failed' },
      { status: 401 }
    )
  }
}
proxy.js
import { isAuthenticated } from '@lib/auth'

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

export function proxy(request) {
  if (!isAuthenticated(request)) {
    return Response.json(
      { success: false, message: 'authentication failed' },
      { status: 401 }
    )
  }
}

你还可以使用 proxy 来代理请求。此示例读取 request.nextUrl,因此 request 的类型为 NextRequest:

proxy.ts
import { type NextRequest, NextResponse } from 'next/server'

export function proxy(request: NextRequest) {
  if (request.nextUrl.pathname === '/proxy-this-path') {
    const rewriteUrl = new URL('https://nextjs.org')
    return NextResponse.rewrite(rewriteUrl)
  }
}
proxy.js
import { NextResponse } from 'next/server'

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

proxy 可以产生的另一种响应类型是重定向:

proxy.ts
import { type NextRequest, NextResponse } from 'next/server'

export function proxy(request: NextRequest) {
  if (request.nextUrl.pathname === '/v1/docs') {
    request.nextUrl.pathname = '/v2/docs'
    return NextResponse.redirect(request.nextUrl)
  }
}
proxy.js
import { NextResponse } from 'next/server'

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

安全性#

处理请求头#

要谨慎处理请求头的去向,避免直接将传入的请求头传递给传出的响应。

  • 上游请求头:在 Proxy 中,NextResponse.next({ request: { headers } }) 会修改服务器接收的请求头,但不会将其暴露给客户端。
  • 响应头:new Response(..., { headers })、NextResponse.json(..., { headers })、NextResponse.next({ headers }) 或 response.headers.set(...) 会将请求头发送回客户端。如果向这些请求头附加了敏感值,客户端将可见。

了解更多信息,请参阅Proxy 中的 NextResponse 请求头。

速率限制#

你可以在 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: 'Rate limit exceeded' }, { status: 429 })
  }

  return new Response(null, { status: 204 })
}
/app/resource/route.js
import { NextResponse } from 'next/server'
import { checkRateLimit } from '@/lib/rate-limit'

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

  if (rateLimited) {
    return NextResponse.json({ error: 'Rate limit exceeded' }, { status: 429 })
  }

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

将计数保存在内存中的速率限制器会分别跟踪每个服务器实例,并且在实例重启时计数会重置。当你的应用运行在多个实例上时,请将计数保存在共享数据存储中,或使用托管提供商的速率限制。

验证负载#

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

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

将用户生成的静态资源存储在专用服务中。尽可能从浏览器上传这些资源,并将返回的 URI 存储在数据库中,以减小请求大小。

访问受保护资源#

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

Route Handler 中的检查仅在处理程序运行时执行。当响应设置带有 max-age 或 s-maxage 的 Cache-Control: public 时,CDN 可以存储它并为同一 URL 的后续请求提供服务,而无需调用处理程序。CDN 读取哪些请求头以及缓存键中包含哪些内容,取决于你的托管提供商。凭据检查和速率限制不适用于从缓存提供的请求,因此只缓存那些可以安全地提供给任何持有 URL 的人的响应。

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

定期轮换凭据和 API 密钥。

预检请求#

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

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

库模式#

社区库通常会为 Route Handler 使用工厂模式。

/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 自定义行为。

库也可以提供 proxy 工厂。

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

export default createMiddleware()

小知识:第三方库可能仍将 proxy 称为 middleware。

更多示例#

有关使用 Route Handler 和 proxy 的更多示例,请参阅 API 参考。

这些示例包括使用 Cookies、Headers、Streaming、Proxy 否定匹配以及其他有用的代码片段。

注意事项#

Server Component#

在 Server Component 中直接从数据源获取数据,而不要通过 Route Handler。

对于在构建时预渲染的 Server Component,使用 Route Handler 会导致构建步骤失败。这是因为在构建时没有服务器监听这些请求。

对于按需渲染的 Server Component,由于处理程序和渲染进程之间额外的 HTTP 往返,从 Route Handler 获取数据会更慢。

服务器端的 fetch 请求使用绝对 URL。这意味着需要与外部服务器进行 HTTP 往返。在开发期间,你自己的开发服务器充当外部服务器。在构建时没有服务器,而在运行时,服务器通过你面向公众的域名可用。

Server Component 涵盖了大多数数据获取需求。但是,在以下情况下可能需要在客户端获取数据:

  • 依赖于仅限客户端的 Web API 的数据:
    • Geo-location API
    • Storage API
    • Audio API
    • File API
  • 频繁轮询的数据

对于这些情况,请使用 swr 或 react-query 等社区库。

Server Action#

Server Action 使你能够从客户端运行服务器端代码。其主要目的是从前端客户端修改数据。

Server Action 是排队的。将它们用于数据获取会引入顺序执行。

export 模式#

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

在 export mode 中,仅支持 GET Route Handler,并且需结合设置为 'force-static' 的 dynamic 路由段配置。

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

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

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

部署环境#

一些托管提供商将 Route Handler 部署为 lambda 函数。这意味着:

  • Route Handler 无法在请求之间共享数据。
  • 环境可能不支持写入文件系统。
  • 长时间运行的处理程序可能因超时而被终止。
  • WebSockets 将无法工作,因为连接会在超时或生成响应后关闭。
Next.js 中文网