proxy.go
experimental
使用 proxy.go 文件约定编写实验性 Go Proxy(middleware)的 API 参考。
proxy.go 在路由请求之前运行 Go 代码,使用 Go 的 net/http 请求和响应 API。
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 值:
// 在不修改请求头的情况下继续或重写。
Next(w)
Rewrite(w, "/destination")ProxyOptions#
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。
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。
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 的适配器。