构建带自定义Koa服务器的Next.js生产应用，解决API 404问题

问题根源 #

1. 启动脚本错误：你当前的start命令用的是next start，这会启动Next.js自带的默认服务器，完全没用到你的Koa自定义服务器，自定义API路由自然无法被加载。
2. 生产环境代码兼容性：你的server目录使用ES模块语法（import），生产环境Node.js可能无法直接解析，需要通过Babel处理语法兼容。
3. 请求处理逻辑漏洞：部分请求方法（如POST/PUT）可能被Next.js的兜底路由提前捕获，导致API路由没有机会响应。

修复步骤 #

1. 修改package.json的启动脚本 #

将start命令改为启动你的Koa自定义服务器，同时配置生产环境变量：

"scripts": {
  "dev": "nodemon -r @babel/register ./server/index.js",
  "build": "next build",
  "start": "cross-env NODE_ENV=production node -r @babel/register ./server/index.js",
  // 其余脚本保持不变
}

• cross-env用于跨平台统一设置环境变量，你的devDependencies中已包含该依赖。
• -r @babel/register让Node.js在运行时实时编译ES模块语法，无需手动预编译server目录。

2. 调整Koa中间件顺序与请求处理逻辑 #

确保自定义API路由的中间件优先于Next.js页面路由执行，同时优化请求覆盖范围：

// server/index.js
(async () => {
  try {
    await app.prepare();
    const db = await MongoClientConnection.Get();
    server.context.db = db;

    // 先加载自定义API路由与cookie中间件
    server.use(cookie());
    server.use(UserRouter.routes()).use(UserRouter.allowedMethods());
    server.use(DataRouter.routes()).use(DataRouter.allowedMethods());
    server.use(EmailRouter.routes()).use(EmailRouter.allowedMethods());

    // 再处理Next.js页面路由
    const handleRequest = async (ctx) => {
      await handler(ctx.req, ctx.res);
      ctx.respond = false;
      // 移除硬编码的statusCode，保留Next.js自身的响应状态
    };

    router.get('/custom-page', async (ctx) => {
      await app.render(ctx.req, ctx.res, '/', ctx.query);
      ctx.respond = false;
    });
    
    router.get('/_next/webpack-hmr', handleRequest);
    // 用all方法处理所有HTTP请求，避免非GET请求被遗漏
    router.all('(.*)', handleRequest);

    server.use(router.routes());
    server.listen(port, (_) => console.log(`App running on port ${port} (${dev ? '开发环境' : '生产环境'})`));
  } catch (e) {
    console.error(e);
    process.exit(1);
  }
})();

• 将API路由中间件移至Next.js路由之前，确保API请求优先被处理。
• 把router.get('(.*)')改为router.all('(.*)')，覆盖所有HTTP方法的页面请求。
• 删除硬设的ctx.res.statusCode = 200，避免覆盖Next.js返回的真实响应状态码。

3. 优化生产环境环境变量加载 #

如果生产环境需要从单独的环境文件加载变量，可修改dotenv配置：

// server/index.js
dotenv.config({ path: dev ? '.env' : '.env.production' });

验证流程 #

1. 执行项目构建：yarn build
2. 启动生产服务器：yarn start
3. 测试API路由，确认不再返回404错误。

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