PayloadCMS项目构建报错：cloudflare:sockets未被Webpack插件处理

我是PayloadCMS新手，基于空白模板创建了第一个项目。执行pnpm build命令构建时，Webpack编译失败，报错信息如下：
UnhandledSchemeError: Reading from "cloudflare:sockets" is not handled by plugins
提示Webpack默认仅支持"data:"和"file:" URI，需要额外插件处理"cloudflare:"协议，但我并未为PostgreSQL配置任何Cloudflare相关内容，搜索资料、咨询ChatGPT均未找到有效解决方案。

完整错误日志 #

[black-purple@MacBook-Pro.local project-name ]$ pnpm build

> project-name@1.0.0 build /Users/black-purple/Documents/code/my-lms/project-name
> cross-env NODE_OPTIONS=--no-deprecation next build

 ⚠ The config property `experimental.turbo` is deprecated. Move this setting to `config.turbopack` as Turbopack is now stable.
   ▲ Next.js 15.3.0
   - Environments: .env

   Creating an optimized production build ...
Failed to compile.

cloudflare:sockets
Module build failed: UnhandledSchemeError: Reading from "cloudflare:sockets" is not handled by plugins (Unhandled scheme).
Webpack supports "data:" and "file:" URIs by default.
You may need an additional plugin to handle "cloudflare:" URIs.
    at /Users/black-purple/Documents/code/my-lms/project-name/node_modules/.pnpm/next@15.3.0_react-dom@19.1.0_react@19.1.0__react@19.1.0_sass@1.77.4/node_modules/next/dist/compiled/webpack/bundle5.js:29:408376
    at Hook.eval [as callAsync] (eval at create (/Users/black-purple/Documents/code/my-lms/project-name/node_modules/.pnpm/next@15.3.0_react-dom@19.1.0_react@19.1.0__react@19.1.0_sass@1.77.4/node_modules/next/dist/compiled/webpack/bundle5.js:14:9224), <anonymous>:6:1)
    at Object.processResource (/Users/black-purple/Documents/code/my-lms/project-name/node_modules/.pnpm/next@15.3.0_react-dom@19.1.0_react@19.1.0__react@19.1.0_sass@1.77.4/node_modules/next/dist/compiled/webpack/bundle5.js:29:408301)
    at processResource (/Users/black-purple/Documents/code/my-lms/project-name/node_modules/.pnpm/next@15.3.0_react-dom@19.1.0_react@19.1.0__react@19.1.0_sass@1.77.4/node_modules/next/dist/compiled/loader-runner/LoaderRunner.js:1:5308)
    at iteratePitchingLoaders (/Users/black-purple/Documents/code/my-lms/project-name/node_modules/.pnpm/next@15.3.0_react-dom@19.1.0_react@19.1.0__react@19.1.0_sass@1.77.4/node_modules/next/dist/compiled/loader-runner/LoaderRunner.js:1:4667)
    at runLoaders (/Users/black-purple/Documents/code/my-lms/project-name/node_modules/.pnpm/next@15.3.0_react-dom@19.1.0_react@19.1.0__react@19.1.0_sass@1.77.4/node_modules/next/dist/compiled/loader-runner/LoaderRunner.js:1:8590)
    at NormalModule._doBuild (/Users/black-purple/Documents/code/my-lms/project-name/node_modules/.pnpm/next@15.3.0_react-dom@19.1.0_react@19.1.0__react@19.1.0_sass@1.77.4/node_modules/next/dist/compiled/webpack/bundle5.js:29:408163)
    at NormalModule.build (/Users/black-purple/Documents/code/my-lms/project-name/node_modules/.pnpm/next@15.3.0_react-dom@19.1.0_react@19.1.0__react@19.1.0_sass@1.77.4/node_modules/next/dist/compiled/webpack/bundle5.js:29:410176)
    at /Users/black-purple/Documents/code/my-lms/project-name/node_modules/.pnpm/next@15.3.0_react-dom@19.1.0_react@19.1.0__react@19.1.0_sass@1.77.4/node_modules/next/dist/compiled/webpack/bundle5.js:29:82494
    at NormalModule.needBuild (/Users/black-purple/Documents/code/my-lms/project-name/node_modules/.pnpm/next@15.3.0_react-dom@19.1.0_react@19.1.0__react@19.1.0_sass@1.77.4/node_modules/next/dist/compiled/webpack/bundle5.js:29:414160)

Import trace for requested module:
cloudflare:sockets
./node_modules/.pnpm/pg-cloudflare@1.2.5/node_modules/pg-cloudflare/dist/index.js
./node_modules/.pnpm/pg@8.11.3/node_modules/pg/lib/stream.js
./node_modules/.pnpm/pg@8.11.3/node_modules/pg/lib/connection.js
./node_modules/.pnpm/pg@8.11.3/node_modules/pg/lib/index.js
./node_modules/.pnpm/@payloadcms+db-postgres@3.33.0_@types+react@19.1.0_payload@3.33.0_graphql@16.11.0_typescript@5.7.3__react@19.1.0/node_modules/@payloadcms/db-postgres/dist/connect.js
./node_modules/.pnpm/@payloadcms+db-postgres@3.33.0_@types+react@19.1.0_payload@3.33.0_graphql@16.11.0_typescript@5.7.3__react@19.1.0/node_modules/@payloadcms/db-postgres/dist/index.js
./src/payload.config.ts
./src/app/(frontend)/(auth)/_actions/actions.ts

cloudflare:sockets
Module build failed: UnhandledSchemeError: Reading from "cloudflare:sockets" is not handled by plugins (Unhandled scheme).
Webpack supports "data:" and "file:" URIs by default.
You may need an additional plugin to handle "cloudflare:" URIs.
    at /Users/black-purple/Documents/code/project-name/node_modules/.pnpm/next@15.3.0_react-dom@19.1.0_react@19.1.0__react@19.1.0_sass@1.77.4/node_modules/next/dist/compiled/webpack/bundle5.js:29:408376
    at Hook.eval [as callAsync] (eval at create (/Users/black-purple/Documents/code/project-name/node_modules/.pnpm/next@15.3.0_react-dom@19.1.0_react@19.1.0__react@19.1.0_sass@1.77.4/node_modules/next/dist/compiled/webpack/bundle5.js:14:9224), <anonymous>:6:1)
    at Hook.CALL_ASYNC_DELEGATE [as _callAsync] (/Users/black-purple/Documents/code/project-name/node_modules/.pnpm/next@15.3.0_react-dom@19.1.0_react@19.1.0__react@19.1.0_sass@1.77.4/node_modules/next/dist/compiled/webpack/bundle5.js:14:6378)
    at Object.processResource (/Users/black-purple/Documents/code//project-name/node_modules/.pnpm/next@15.3.0_react-dom@19.1.0_react@19.1.0__react@19.1.0_sass@1.77.4/node_modules/next/dist/compiled/webpack/bundle5.js:29:408301)
    at processResource (/Users/black-purple/Documents/code//project-name/node_modules/.pnpm/next@15.3.0_react-dom@19.1.0_react@19.1.0__react@19.1.0_sass@1.77.4/node_modules/next/dist/compiled/loader-runner/LoaderRunner.js:1:5308)
    at iteratePitchingLoaders (/Users/black-purple/Documents/code/project-name/node_modules/.pnpm/next@15.3.0_react-dom@19.1.0_react@19.1.0__react@19.1.0_sass@1.77.4/node_modules/next/dist/compiled/loader-runner/LoaderRunner.js:1:4667)
    at runLoaders (/Users/black-purple/Documents/code/project-name/node_modules/.pnpm/next@15.3.0_react-dom@19.1.0_react@19.1.0__react@19.1.0_sass@1.77.4/node_modules/next/dist/compiled/loader-runner/LoaderRunner.js:1:8590)
    at NormalModule._doBuild (/Users/black-purple/Documents/code/project-name/node_modules/.pnpm/next@15.3.0_react-dom@19.1.0_react@19.1.0__react@19.1.0_sass@1.77.4/node_modules/next/dist/compiled/webpack/bundle5.js:29:408163)
    at NormalModule.build (/Users/black-purple/Documents/code/project-name/node_modules/.pnpm/next@15.3.0_react-dom@19.1.0_react@19.1.0__react@19.1.0_sass@1.77.4/node_modules/next/dist/compiled/webpack/bundle5.js:29:410176)
    at /Users/black-purple/Documents/code/project-name/node_modules/.pnpm/next@15.3.0_react-dom@19.1.0_react@19.1.0__react@19.1.0_sass@1.77.4/node_modules/next/dist/compiled/webpack/bundle5.js:29:82494

Import trace for requested module:
cloudflare:sockets
./node_modules/.pnpm/pg-cloudflare@1.2.5/node_modules/pg-cloudflare/dist/index.js
./node_modules/.pnpm/pg@8.11.3/node_modules/pg/lib/stream.js
./node_modules/.pnpm/pg@8.11.3/node_modules/pg/lib/connection.js
./node_modules/.pnpm/pg@8.11.3/node_modules/pg/lib/index.js
./node_modules/.pnpm/@payloadcms+db-postgres@3.33.0_@types+react@19.1.0_payload@3.33.0_graphql@16.11.0_typescript@5.7.3__react@19.1.0/node_modules/@payloadcms/db-postgres/dist/connect.js
./node_modules/.pnpm/@payloadcms+db-postgres@3.33.0_@types+react@19.1.0_payload@3.33.0_graphql@16.11.0_typescript@5.7.3__react@19.1.0/node_modules/@payloadcms/db-postgres/dist/index.js
./src/payload.config.ts
./src/app/(payload)/api/graphql-playground/route.ts


> Build failed because of webpack errors
 ELIFECYCLE  Command failed with exit code 1.

解决方案 #

方案1：配置Next.js Webpack忽略cloudflare:sockets协议 #

在项目根目录的next.config.js中添加Webpack配置，让它忽略该协议的解析：

/** @type {import('next').NextConfig} */
const nextConfig = {
  webpack: (config) => {
    config.resolve.fallback = {
      ...config.resolve.fallback,
      "cloudflare:sockets": false,
    };
    return config;
  },
};

module.exports = nextConfig;

方案2：隔离数据库连接代码到服务器端 #

从错误追踪可以看到，前端代码（如_actions/actions.ts、graphql-playground/route.ts）直接引入了包含数据库连接逻辑的payload.config.ts。需要调整代码结构：

• 将数据库初始化、Payload配置相关逻辑封装为仅服务器端可用的模块
• 在Server Actions、API路由或Server Components中导入该模块，避免客户端代码加载数据库连接依赖

方案3：强制替换pg-cloudflare依赖（可选） #

如果确认不需要Cloudflare环境支持，可以通过pnpm的依赖覆盖功能，让pg使用普通的socket实现：
在package.json中添加如下配置：

{
  "pnpm": {
    "overrides": {
      "pg-cloudflare": "npm:pg@^8.11.3"
    }
  }
}

执行pnpm install重新安装依赖后再尝试构建。

内容的提问来源于stack exchange，提问作者black-purple