故障排除
"您的 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 —— 可能有一些不必要的代码进入了您的生产环境打包包中。您可以通过运行以下命令来可视化并理解这一点:
- 在项目根目录内运行
npx @opennextjs/cloudflare build cd .open-next/server-functions/default打开包含打包代码的目录- 获取名为
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.toml 或 wrangler.jsonc 中的 compatibility_date 更新为 2025-05-05 或更高版本:
{
"compatibility_date": "2025-05-05"
}有关更多详细信息,请参阅 Cloudflare Workers 兼容性标志文档 (opens in a new tab)。