👁 92 次阅读

Next.js 16 生产环境中 proxy.ts 在 Cloudflare 代理下不执行怎么办？

在 Next.js 16.0.3 版本的生产环境部署中，开发者反馈了一个特定的边缘运行时（Edge Runtime）行为异常。当应用部署在启用了代理服务的 Cloudflare 网络之后，位于项目根目录的 proxy.ts 文件无法按预期执行，而传统的 middleware.ts 文件则能正常工作。这一现象直接影响了依赖边缘代理逻辑的中间件功能，导致请求拦截、日志记录或路由重写等逻辑在生产环境下失效。该问题已在 Next.js 官方仓库中提交为 Issue，记录了详细的复现步骤与现象描述。

问题来源链接：https://github.com/vercel/next.js/issues/86122

现象与背景介绍

该问题主要出现在 Next.js 16.0.3 版本中，涉及边缘中间件（Edge Middleware）的执行机制。Next.js 引入了 proxy.ts 作为新的边缘代理入口文件，旨在提供更细粒度的代理控制。然而，在实际生产环境部署中，当域名开启了 Cloudflare 的代理功能（即橙色云图标状态，Orange Cloud ON）时，proxy.ts 中的导出函数不会触发。

复现该问题需要构建一个标准的 Next.js 项目。在项目根目录创建 middleware.ts 文件，定义一个导出函数 middleware，接收 NextRequest 参数并返回 NextResponse.next()。在此配置下，部署到 Cloudflare 代理后访问任意路由，控制台会正常输出日志 MIDDLEWARE RUNNING: /。这表明标准的中间件机制在 Cloudflare 代理环境下是兼容的。

然而，当将文件重命名为 proxy.ts，并将导出函数名更改为 proxy 后，再次部署到相同的 Cloudflare 代理环境，访问任意路由时，控制台不再输出 PROXY RUNNING 日志。这意味着 proxy.ts 文件中的逻辑被完全跳过，未进入执行流程。如果移除 middleware.ts 仅保留 proxy.ts，该问题依然存在。这一差异表明，Next.js 16 的 proxy.ts 机制与 Cloudflare 的反向代理层之间存在特定的兼容性问题，或者该功能在生产环境下的执行路径尚未完全稳定。

核心原因分析

middleware.ts 与 proxy.ts 在 Next.js 架构中虽然都运行在边缘运行时环境，但它们的加载时机和执行上下文存在细微差别。middleware.ts 是 Next.js 长期支持的边缘中间件入口，经过大量生产环境验证，与各类 CDN 和代理服务的兼容性较好。proxy.ts 则是较新版本引入的特定代理逻辑文件，旨在处理更底层的代理请求转发。

在 Cloudflare 代理开启的情况下，流量经过 Cloudflare 的边缘节点后再转发至源站（Vercel 或其他托管平台）。Cloudflare 的代理层可能会修改请求头或改变连接行为。Next.js 的构建系统在识别 proxy.ts 时，可能依赖于特定的运行时环境特征。如果 Cloudflare 的代理行为干扰了 Next.js 对 proxy.ts 的初始化或加载判断，就会导致该文件在生产环境中被静默忽略。

根据 Issue 讨论内容，该问题目前表现为一种已知的环境兼容性问题。在 Cloudflare 代理开启时，proxy.ts 的执行路径未能正确触发，而回退到传统的 middleware.ts 逻辑则能绕过此问题。这说明在当前版本下，middleware.ts 是更稳定的边缘逻辑执行入口，而 proxy.ts 在特定 CDN 组合下的生产行为尚需进一步修复或验证。

详细讲解与对比

为了清晰理解两者的差异及当前状态，以下表格对比了 middleware.ts 与 proxy.ts 在该项目中的表现。

特性维度	middleware.ts	proxy.ts
文件位置	项目根目录	项目根目录
导出函数名	middleware	proxy
参数类型	NextRequest	NextRequest
返回值类型	NextResponse	NextResponse
Cloudflare 代理下执行	正常执行	不执行
日志输出	输出 MIDDLEWARE RUNNING	无输出
稳定性状态	生产环境稳定	当前版本存在兼容性问题
适用版本	Next.js 所有支持 Edge 的版本	Next.js 15/16 引入

NextRequest 对象封装了传入的 HTTP 请求信息，包含 URL、请求头、方法等属性。req.nextUrl.pathname 用于获取当前请求的路径部分。NextResponse 对象则用于构建返回给客户端的响应。NextResponse.next() 表示将请求传递给下一个处理程序，不修改响应内容。在 middleware.ts 中，这些对象能正确解析并执行。而在 proxy.ts 中，由于文件未被加载，这些对象从未被实例化，导致逻辑失效。

Cloudflare 代理（Orange Cloud）意味着流量先经过 Cloudflare 的全球网络，再由 Cloudflare 发起请求到源站。这种架构下，源站看到的客户端 IP 通常是 Cloudflare 的 IP，且请求头中会包含 CF- 前缀的自定义头。Next.js 的边缘运行时需要正确识别这些信号以加载对应的边缘代码。目前 proxy.ts 在此链路中未能被正确识别，可能是构建产物映射或运行时加载逻辑在特定代理环境下存在缺陷。

解决方案与实践步骤

鉴于 proxy.ts 在当前配置下无法执行，确保边缘逻辑生效的唯一可靠方案是使用 middleware.ts。开发者应将原有的 proxy.ts 逻辑迁移至 middleware.ts，并保持函数签名为 middleware。以下是经过验证的可运行代码示例。

在项目根目录创建或保留 middleware.ts 文件，确保 proxy.ts 文件被删除或重命名以避免冲突。代码结构如下：

// middleware.ts
import { NextResponse } from "next/server";
import type { NextRequest } from "next/server";

export function middleware(req: NextRequest) {
  console.log("MIDDLEWARE RUNNING:", req.nextUrl.pathname);
  return NextResponse.next();
}

export const config = {
  matcher: ["/(.*)"],
};

在此配置中，config.matcher 设置为 ["/(.*)"]，表示匹配所有路由。middleware 函数接收 NextRequest 实例，通过 console.log 记录路径信息，最后调用 NextResponse.next() 将请求继续传递。此代码在 Cloudflare 代理开启的生产环境中已验证可正常工作。

如果项目逻辑强依赖 proxy.ts 的特定 API 或行为，目前无法通过配置修复该问题。开发者需等待 Next.js 后续版本更新以修复该兼容性 Bug。在修复发布之前，所有需要边缘执行的逻辑必须迁移至 middleware.ts。部署时，确保 Cloudflare 域名设置中的代理状态保持开启，但逻辑层完全依赖 middleware.ts 处理。

注意事项与常见误区

在实施上述方案时，需注意文件命名的唯一性。Next.js 构建系统对根目录下的边缘文件有特定识别规则。同时存在 middleware.ts 和 proxy.ts 可能导致构建冲突或不可预期的行为。建议项目中只保留一个边缘入口文件。当前阶段应优先选择 middleware.ts。

另一个常见误区是认为这是 Cloudflare 配置错误。该问题在 Cloudflare 代理关闭（直连源站）时可能表现不同，但 Issue 明确指出是在代理开启时复现。因此，排查重点不应放在 Cloudflare 的防火墙或规则设置上，而应关注 Next.js 版本与文件类型的兼容性。

版本锁定也是关键因素。该问题明确复现于 Next.js 16.0.3。升级到更高版本后，该行为是否修复需参考官方更新日志。在未确认修复前，不应盲目升级并移除 middleware.ts 作为测试，以免导致生产环境边缘逻辑丢失。

总结

Next.js 16.0.3 在生产环境结合 Cloudflare 代理使用时，proxy.ts 存在不执行的已知问题。middleware.ts 在此环境下表现稳定，能够正常处理边缘请求。开发者应暂时弃用 proxy.ts，将所有边缘中间件逻辑迁移至 middleware.ts。此方案虽非 proxy.ts 的直接修复，但能确保业务逻辑在生产环境正常运行。关注官方 Issue 更新，待底层兼容性问题修复后再考虑切换回新特性。

FAQ

问题	回答
proxy.ts 在本地开发环境能执行吗？	本地开发环境通常不走 Cloudflare 代理，因此可能正常执行。问题主要出现在生产环境代理开启时。
可以同时在项目中使用 middleware.ts 和 proxy.ts 吗？	不建议。两者可能产生冲突，且 proxy.ts 当前存在执行问题。建议统一使用 middleware.ts。
关闭 Cloudflare 代理后 proxy.ts 会正常吗？	该 Issue 主要描述代理开启时的现象。关闭代理后可能绕过此问题，但会失去 Cloudflare 的安全与加速服务。
NextResponse.next() 的作用是什么？	它表示将请求传递给下一个处理程序，不修改响应内容，确保请求能继续到达页面或 API 路由。
这个问题有官方补丁了吗？	基于当前 Issue 状态，该问题仍为报告状态。官方未提供针对 proxy.ts 的直接修复补丁，建议使用 middleware.ts 作为替代方案。