Next.js 13.5.6部署Cloudflare Workers时getServerSideProps与edge运行时异常

排查步骤 #

1. 检查getServerSideProps与Edge Runtime的兼容性 #

• Next.js 13的getServerSideProps在experimental-edge运行时下有严格限制：禁止使用Node.js内置模块（如fs、path、crypto的Node版本），必须替换为Web标准API。
• 即使开启nodejs_compat兼容标志，部分Node API仍无法在Cloudflare Workers环境正常运行，比如process.cwd()、require()等。

2. 修正构建与环境变量配置 #

• 移除pages:build脚本中的env-cmd，@cloudflare/next-on-pages会自动读取项目根目录的.env文件，或通过wrangler.toml注入环境变量：

  "pages:build": "npx @cloudflare/next-on-pages",
  

• 在next.config.js中全局配置Edge Runtime（或在单个页面中单独配置）：

  module.exports = {
    experimental: {
      runtime: 'experimental-edge',
    },
  };
  

  单个页面配置示例：

  export const config = {
    runtime: 'experimental-edge',
  };
  
  export async function getServerSideProps(context) {
    // 业务逻辑
    return { props: {} };
  }
  

3. 本地复现错误（优先排查） #

• 使用npm run pages:dev启动Cloudflare Pages本地开发环境，而非next dev——后者是Next.js原生环境，无法模拟Cloudflare Workers的限制。
• 访问出错页面，查看终端输出的详细错误日志，这比Cloudflare后台日志更直观。

4. 同步兼容性配置到部署环境 #

• 将本地开发用的兼容性标志和日期写入wrangler.toml，确保部署后的Worker环境与本地一致：

  [[pages]]
  name = "你的项目名称"
  directory = ".vercel/output/static"
  compatibility_date = "2023-12-06"
  compatibility_flags = ["nodejs_compat"]
  

5. 捕获详细错误日志 #

• 在getServerSideProps中添加错误捕获，输出详细日志到Cloudflare Workers：

  export async function getServerSideProps(context) {
    try {
      // 原有业务逻辑
      return { props: {} };
    } catch (err) {
      console.error('getServerSideProps 错误详情:', err.stack);
      // 可选：返回错误信息到页面便于调试
      return { props: { error: err.message } };
    }
  }
  

• 部署后查看Cloudflare Workers的实时日志（而非Pages日志），获取具体错误栈。

6. 升级依赖版本 #

• 执行以下命令更新@cloudflare/next-on-pages到最新版本，修复与Next.js 13.5.6的兼容性问题：

  npm update @cloudflare/next-on-pages
  

内容的提问来源于stack exchange，提问作者Amitprj