如何将 Next.js 用作前端的后端
了解如何将 Next.js 用作后端框架
Next.js 支持“前端的后端(Backend for Frontend)”模式。这使你可以创建公共端点来处理 HTTP 请求并返回任何内容类型——而不仅仅是 HTML。你还可以访问数据源并执行更新远程数据等副作用。
如果你要开始一个新项目,使用带有 --api 标志的 create-next-app 会自动在新项目的 app/ 文件夹中包含一个示例 route.ts,演示如何创建 API 端点。
pnpm create next-app --apinpx create-next-app@latest --apiyarn create next-app --apibun create next-app --api小知识:Next.js 的后端能力并非完整后端的替代品。它们充当 API 层,具备以下特点:
- 可公开访问
- 处理任何 HTTP 请求
- 可返回任何内容类型
要实现此模式,请使用:
- Route Handler
proxy- 在 Pages Router 中,API Routes
公共端点#
Route Handler 是公共 HTTP 端点。任何客户端都可以访问它们。
使用 route.ts 或 route.js 文件约定创建 Route Handler:
export function GET(request: Request) {}export function GET(request) {}这将处理发送到 /api 的 GET 请求。
对于可能抛出异常的操作,请使用 try/catch 块:
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 })
}
}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.txtrss.xml.well-known
例如,app/rss.xml/route.ts 会为 rss.xml 创建一个 Route Handler。
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 })
}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:
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:
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',
},
})
}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 测试:
# 返回 Markdown
curl -H "Accept: text/markdown" https://example.com/docs/getting-started
# 返回普通的 HTML 页面
curl https://example.com/docs/getting-started小知识:
使用请求负载#
使用 Request 的实例方法(如 .json()、.formData() 或 .text())来访问请求正文。
GET 和 HEAD 请求不带正文。
export async function POST(request: Request) {
const res = await request.json()
return Response.json({ res })
}export async function POST(request) {
const res = await request.json()
return Response.json({ res })
}小知识:在将数据传递给其他系统之前对其进行验证
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 })
}
}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 })
}
}请求正文只能读取一次。如果需要再次读取,请克隆请求:
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 })
}
}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 可以转换、过滤和聚合来自一个或多个数据源的数据。这使逻辑远离前端,并避免暴露内部系统。
你还可以将繁重的计算卸载到服务器,减少客户端的电量和数据使用量。
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 })
}
}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,调用者无法将请求或其令牌指向其他目标。
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 })
}
}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。
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 })
}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 配置为在发生更改时调用特定端点。
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 })
}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 验证响应并决定将用户重定向到何处。
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
}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
}重定向#
import { redirect } from 'next/navigation'
export async function GET(request: Request) {
redirect('https://nextjs.org/')
}import { redirect } from 'next/navigation'
export async function GET(request) {
redirect('https://nextjs.org/')
}了解更多关于 redirect 和 permanentRedirect 中的重定向信息。
Proxy#
每个项目只允许一个 proxy 文件。使用 config.matcher 来定位特定路径。了解更多关于 proxy 的信息。
使用 proxy 在请求到达路由路径之前生成响应。
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 }
)
}
}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:
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)
}
}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 可以产生的另一种响应类型是重定向:
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)
}
}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 后端实现速率限制。除了基于代码的检查外,还应启用托管提供商提供的任何速率限制功能。
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 })
}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 使用工厂模式。
import { createHandler } from 'third-party-library'
const handler = createHandler({
/* 库特定的选项 */
})
export const GET = handler
// 或
export { handler as POST }这会为 GET 和 POST 请求创建一个共享的处理程序。该库根据请求中的 method 和 pathname 自定义行为。
库也可以提供 proxy 工厂。
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 或其他文件。
export const dynamic = 'force-static'
export function GET() {
return new Response('Hello World', { status: 200 })
}部署环境#
一些托管提供商将 Route Handler 部署为 lambda 函数。这意味着:
- Route Handler 无法在请求之间共享数据。
- 环境可能不支持写入文件系统。
- 长时间运行的处理程序可能因超时而被终止。
- WebSockets 将无法工作,因为连接会在超时或生成响应后关闭。