NNext.js 中文网 GitHub

skipProxyUrlNormalize

让 Proxy 看到原始请求,而不是 Next.js 规范化后的版本。旧名为 skipMiddlewareUrlNormalize。

启用 skipProxyUrlNormalize 可让 Proxy 看到原始请求,而不是 Next.js 规范化后的版本。这包括内部 URL、查询参数以及客户端导航期间使用的请求头。

大多数项目不需要此选项。 它是高级 Proxy 标志之一,适用于特定的路由场景和调试。

next.config.ts
import type { NextConfig } from 'next'

const nextConfig: NextConfig = {
  skipProxyUrlNormalize: true,
}

export default nextConfig
next.config.js
/** @type {import('next').NextConfig} */
const nextConfig = {
  skipProxyUrlNormalize: true,
}

module.exports = nextConfig

参考#

在客户端导航期间,Next.js 使用内部请求,而不是将目标 URL 作为完整文档加载来请求。默认情况下,Next.js 会在该请求到达 Proxy 之前对其进行规范化,因此 Proxy 在客户端导航和完整页面加载时看到的目标 URL 相同。

Next.js 还会规范化 Proxy 返回的内容,因此你重写或重定向到的任何 URL 都会被相应地重写。

使用 skipProxyUrlNormalize: true 时,这两种规范化都不会执行。Proxy 接收按原样发送的请求,其重写或重定向到的目标也按写入的内容发送:

默认使用 skipProxyUrlNormalize: true 时
request.nextUrl 将内部数据 URL 解析回路由路径并提取区域设置保留按原样发送的请求路径名
request.url 是规范化后的 URL是原始请求 URL
内部 _rsc 查询参数被移除保留
Next.js 内部导航请求头(rsc、next-router-state-tree、next-router-prefetch、next-router-segment-prefetch、next-hmr-refresh)会从 request.headers 中移除保留
NextResponse.rewrite() 的目标会使用构建 ID 重新序列化按写入内容发送
NextResponse.redirect() 的 Location 会被重写为相对 URL按写入内容发送,保留尾部斜杠
使用 trailingSlash: true 时,会在 Proxy 运行前追加尾部斜杠路径名原样传递

已弃用的别名#

此选项的旧名称是 skipMiddlewareUrlNormalize,来自 Proxy 还被称为 Middleware 的时期。它仍然有效,但会记录弃用警告。同时设置两者会抛出错误:

Terminal
配置选项 `skipProxyUrlNormalize` 和 `skipMiddlewareUrlNormalize` 不能同时设置。请改用 `skipProxyUrlNormalize`。

version 16 codemod 会为你自动重命名。

小知识#

  • 避免使用内部导航请求头来为客户端导航和完整页面加载返回不同的内容。
  • 你不需要此选项来限制 Proxy 在哪些路由上运行。无论哪种情况,matcher 配置仍然基于目标 URL 进行匹配。
  • 只有 Proxy 看到的请求和响应会发生变化。文件系统路由、next.config.js 中的 redirects 和 rewrites 行为保持不变。

示例#

读取客户端发送的原始 URL#

在客户端导航期间,Next.js 会向请求添加 _rsc 查询参数及其内部导航请求头。启用该选项后,Proxy 可以读取这两者。

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

export default function proxy(request: NextRequest) {
  console.log(request.nextUrl.searchParams.get('_rsc'))
  // 启用时:Next.js 添加到请求中的值
  // 禁用时:null

  console.log(request.headers.get('rsc'))
  // 启用时:客户端导航期间为 '1'
  // 禁用时:null
}
proxy.js
export default function proxy(request) {
  console.log(request.nextUrl.searchParams.get('_rsc'))
  // 启用时:Next.js 添加到请求中的值
  // 禁用时:null

  console.log(request.headers.get('rsc'))
  // 启用时:客户端导航期间为 '1'
  // 禁用时:null
}

在客户端导航期间,Next.js 会请求 /_next/data URL 而不是目标 URL。启用该选项后,Proxy 会看到按原样发送的该 URL。

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

export default function proxy(request: NextRequest) {
  const { pathname } = request.nextUrl

  // 请求:GET /_next/data/build-id/hello.json
  console.log(pathname)
  // 启用时:/_next/data/build-id/hello.json
  // 禁用时:/hello
}
proxy.js
export default function proxy(request) {
  const { pathname } = request.nextUrl

  // 请求:GET /_next/data/build-id/hello.json
  console.log(pathname)
  // 启用时:/_next/data/build-id/hello.json
  // 禁用时:/hello
}

版本历史#

版本变更
v16.0.0从 skipMiddlewareUrlNormalize 重命名为 skipProxyUrlNormalize。
v13.1.0新增 skipMiddlewareUrlNormalize。
Next.js 中文网