Cloudflare
故障排除

故障排除

"您的 Worker 超出了 3 MiB 的大小限制"

您部署到的 Cloudflare 账户位于 Workers 免费计划上,该计划 将每个 Worker 的大小限制为 3 MiB (opens in a new tab)。当您订阅 Workers 付费计划时,每个 Worker 最大可达 10 MiB。

部署 Worker 时,wrangler 会显示原始大小和压缩后的大小。只有后者(gzip 压缩后的大小)与这些限制相关。

"您的 Worker 超出了 10 MiB 的大小限制"

如果您的 Worker 压缩后大于 10 MiB —— 可能有一些不必要的代码进入了您的生产环境打包包中。您可以通过运行以下命令来可视化并理解这一点:

  1. 在项目根目录内运行 npx @opennextjs/cloudflare build
  2. cd .open-next/server-functions/default 打开包含打包代码的目录
  3. 获取名为 handler.mjs.meta.json 的文件,并使用 ESBuild Bundle Analyzer (opens in a new tab) 来可视化您的应用程序代码,并了解生产环境打包包中最大的部分

导入特定 NPM 包时我的应用构建失败

首先,确保在您的 wrangler 配置文件 (opens in a new tab) 中启用了 nodejs_compat 兼容性标志,并且您的兼容性日期设置为 "2024-09-23" 或之后。 有关 Cloudflare Workers 中 Node.js 支持的更多详细信息,请参阅 Node.js Workers 文档 (opens in a new tab)

某些 NPM 包定义了多个导出。例如:

"exports": {
    "other": "./src/other.js",
    "node": "./src/node.js",
    "browser": "./src/browser.js",
    "default": "./src/default.js"
},

当您使用 @opennextjs/cloudflare 时,Wrangler (opens in a new tab) 会在本地运行代码或将其部署到 Cloudflare 之前打包您的代码。当您导入模块时,Wrangler 必须选择使用哪个导出。默认情况下,使用 esbuild (opens in a new tab) 的 Wrangler 处理此问题的方式与某些 NPM 包不兼容。

您可能希望修改 Wrangler 解析多个导出的方式,以便在导入包时使用 node 导出(如果存在)。您可以通过在 Next.js 应用根目录下的 .env 文件中定义以下变量来实现:

WRANGLER_BUILD_CONDITIONS=""
WRANGLER_BUILD_PLATFORM="node"

Error: Cannot perform I/O on behalf of a different request.

某些数据库客户端(例如 postgres (opens in a new tab))在首次实例化时创建到数据库服务器的连接,并在后续请求中重用该连接。 这种编程模型与 Workers 运行时不兼容,因为在不同的请求中无法重用连接。

在这种情况下会生成以下错误:

⨯ Error: Cannot perform I/O on behalf of a different request. I/O objects (such as streams, request/response bodies, and others) created in the context of one request handler cannot be accessed from a different request's handler. This is a limitation of Cloudflare Workers which allows us to improve overall performance. (I/O type: Writable)

为解决此问题,您应该在请求上下文内创建数据库客户端,而不是保留全局数据库客户端。

全局客户端无法工作:

// src/lib/db.ts
import postgres from "postgres";
 
// `client` 是全局的。
// 由于连接将在请求间共享,它在 worker 上会失败
export const client = postgres(process.env.DATABASE_URL, { max: 5 });
 
// src/app/api/route.ts
import { client } from "@/db/db";
 
export const dynamic = "force-dynamic";
 
export async function GET() {
  return new Response(JSON.stringify(await client`SELECT * FROM users;`));
}

可以通过为每个传入请求创建客户端来修复此问题:

// src/app/api/route.ts
export const dynamic = "force-dynamic";
 
export async function GET() {
  // 客户端为每个传入请求创建,并且没有连接在请求间共享
  const client = postgres(process.env.DATABASE_URL, { max: 5 });
  return new Response(JSON.stringify(await client`SELECT * FROM users;`));
}

Error: Failed to load chunk server/chunks/ssr/<chunk_name>.js

如果您看到类似以下的错误:

✘ [ERROR] ⨯ Error: Failed to load chunk server/chunks/ssr/<chunk_name>.js

      at loadChunkPath
  (...)
      at Object.loadChunk
  (...)
      at .open-next/server-functions/default/.next/server/app/page.js

您可能正在使用带有 Turbopack 构建的旧版本 OpenNext 适配器。请升级 @opennextjs/cloudflare 到最新版本以支持 Turbopack,或使用 Webpack 构建。

X [ERROR] Could not resolve "<package>"

当您在构建期间看到以下错误时:

⚙️ Bundling the OpenNext server...

X [ERROR] Could not resolve "<package name>"

这可能是因为该包包含特定于 workerd 的代码。

查看此 操作指南 以获取解决方案。

ReferenceError: FinalizationRegistry is not defined

如果您在使用依赖现代 JavaScript API 的功能时遇到此错误:

✘ [ERROR] ⨯ ReferenceError: FinalizationRegistry is not defined

发生此错误是因为 FinalizationRegistry API 在较旧的 Cloudflare Workers 兼容性日期中不可用。

要修复此问题,请将 wrangler.tomlwrangler.jsonc 中的 compatibility_date 更新为 2025-05-05 或更高版本:

{
  "compatibility_date": "2025-05-05"
}

有关更多详细信息,请参阅 Cloudflare Workers 兼容性标志文档 (opens in a new tab)