部署在Cloudflare Pages的Next.js+Payload+Express应用API不返回JSON

核心原因 #

Cloudflare Pages默认会将所有未匹配到函数的请求转发到静态首页（index.html），你的/api请求没有被正确路由到Express/Payload后端，导致返回HTML而非JSON。

解决方案步骤 #

1. 配置Cloudflare Pages路由规则 #

在项目根目录的public文件夹下创建_routes.json文件，强制/api路径指向后端函数：

{
  "routes": [
    {
      "src": "/api/**",
      "dest": "/api/index.ts"
    },
    {
      "src": "/*",
      "dest": "/index.html"
    }
  ]
}

这个配置会让所有/api开头的请求优先进入后端函数，其他请求才返回静态首页。

2. 适配Express/Payload到Cloudflare Pages Functions #

Cloudflare Pages Functions基于Cloudflare Workers，不能直接使用普通的Express server.ts入口。需要将后端逻辑适配为Pages Functions格式：

• 在项目根目录创建functions/api/index.ts（对应上面路由的dest路径）
• 将原server.ts中的Payload初始化和路由逻辑迁移到这个文件，示例：

import payload from 'payload';
import { Request, Response } from '@cloudflare/workers-types';

export async function onRequest(context: { request: Request; env: any }) {
  await payload.init({
    secret: context.env.PAYLOAD_SECRET,
    mongoURL: context.env.MONGODB_URI,
    express: false, // 禁用Express，适配Workers环境
  });

  // 处理API请求
  const response = await payload.handleRequest(context.request);
  return response;
}

注意：Payload需要开启express: false来适配Workers环境，同时确保环境变量（如PAYLOAD_SECRET、MONGODB_URI）在Cloudflare Pages控制台中正确配置。

3. 验证前端请求路径 #

检查useUser.ts中的API请求路径，确保生产环境下请求的是正确的/api路径，比如不要硬编码本地地址，用环境变量动态设置：

// useUser.ts示例调整
const baseURL = import.meta.env.PROD ? '/api' : 'http://localhost:3000/api';

async function fetchUser() {
  const res = await fetch(`${baseURL}/users/me`);
  if (!res.ok) throw new Error('Failed to fetch user');
  return res.json();
}

4. 检查Cloudflare Pages函数日志 #

登录Cloudflare Pages控制台，进入你的项目→「Functions」→「Log」，查看/api请求的执行日志，确认是否有报错或未触发函数的情况。

关键说明 #

Cloudflare Pages并没有阻止JSON响应，问题出在路由规则未正确配置，导致API请求被误导向静态首页。按上述步骤调整后，/api路径会正确转发到后端函数，返回JSON数据。

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