NNext.js 中文网 GitHub

proxy.go

experimental

使用 proxy.go 文件约定编写实验性 Go Proxy(middleware)的 API 参考。

proxy.go 在路由请求之前运行 Go 代码,使用 Go 的 net/http 请求和响应 API。

proxy.go
package main

import "net/http"

func Proxy(w http.ResponseWriter, r *http.Request) {
  w.Header().Set("x-proxy", "go")
  Next(w)
}

启用 experimental.goRoutes 并遵循 Go 设置要求。在 app 或 pages 旁边创建 proxy.go,在适用时也创建于 src 内部。导出一个具有上述签名的 Proxy 函数。只有在启用 experimental.goRoutes 时 Next.js 才会检测 proxy.go,且一个项目只能有一个 Proxy 文件:将 proxy.go 与 JavaScript 或 TypeScript Proxy 文件一起使用会报错。

参考#

Next.js 在 proxy 包中生成这些辅助函数:

辅助函数行为
Next(w, options...)继续路由请求。
Rewrite(w, destination, options...)将请求路由到另一个 URL。

两个辅助函数都接受零个或一个 ProxyOptions 值:

go
// 在不修改请求头的情况下继续或重写。
Next(w)
Rewrite(w, "/destination")

ProxyOptions#

go
type ProxyOptions struct {
  Request RequestOptions
}

type RequestOptions struct {
  Headers http.Header
}

Request.Headers 替换下游请求头。替换中省略的请求头会被移除。nil 映射会保留传入的请求头;非 nil 的空映射(http.Header{})会移除所有请求头。请求头名称不区分大小写:仅大小写不同的名称(例如 Foo 和 foo)的值会被合并。传入多个 options 值会引发 panic。

Go 将 Host 存储在 r.Host 中,与 r.Header 分开。克隆请求头时,添加 headers.Set("Host", r.Host) 以保留 Host。

Request.Headers 中的逐跳(hop-by-hop)请求头,例如 Connection、Keep-Alive、Upgrade、Transfer-Encoding 以及 Connection 中列出的请求头,会被忽略,因为它们描述的是到 proxy 的连接,而非下游请求。r.Header 还包含 Next.js 或平台为 proxy 设置的 X-Forwarded-Proto 请求头;克隆的映射会将其转发到下游。如果下游请求不应接收它,请从克隆中删除它。

不调用 Next 或 Rewrite 就直接返回会直接发送响应。使用标准 Go API(例如 http.Redirect、http.SetCookie 和 http.Flusher)来处理重定向、响应 cookie 和流式传输。相对重定向和重写目标会基于传入的 URL 进行解析。

包含 proxy.go 的目录会被编译为一个可执行的 package main,类似于 route.go 目录。对于位于 app 或 pages 旁边的 proxy.go,该目录即项目根目录:该目录中除 _test.go 之外的每个其他 .go 文件都会与其一起编译,并且必须使用 package main。Next.js 会生成 main 函数,因此不要在这些文件中定义 main,也不要创建 zz_next_route_*.go 文件。如果项目根目录已包含 Go 代码(例如 Go 模块的命令),请将 proxy 放在 src/proxy.go,或将该代码移到其自己的目录中。共享代码可以放在导入的包中。

在继续或内部重写请求时,使用 http.SetCookie 设置的 cookie 可以在同一请求的下游渲染中通过 cookies() 获取。

Go Proxy 支持 gzip、zlib-wrapped deflate 和 Brotli 响应压缩。

示例#

重写请求#

调用 Rewrite 将请求路由到另一个路径,同时在浏览器中保留原始 URL。对于应继续而不重写的请求,请调用 Next。

proxy.go
package main

import "net/http"

func Proxy(w http.ResponseWriter, r *http.Request) {
  if r.URL.Path == "/old-path" {
    Rewrite(w, "/new-path")
    return
  }

  Next(w)
}

修改下游请求头#

克隆传入的请求头,应用更改,并通过 ProxyOptions.Request.Headers 传递它们。同一个 options 值既适用于 Next 也适用于 Rewrite。

proxy.go
package main

import "net/http"

func Proxy(w http.ResponseWriter, r *http.Request) {
  headers := r.Header.Clone()
  headers.Set("Host", r.Host)
  headers.Set("x-proxy", "go")
  headers.Del("x-example")
  options := ProxyOptions{
    Request: RequestOptions{Headers: headers},
  }
  Next(w, options)
}

小知识#

  • 默认情况下,Go Proxy 会在每个请求上运行。
  • 仅支持一个 proxy 文件。Go 和 JavaScript proxy 不能组合使用。
  • Go Proxy 需要 Turbopack,并作为编译后的 Go 可执行文件运行。
  • 自托管使用 next build 和 next start。平台部署需要支持 Go middleware 的适配器。
Next.js 中文网