Next.js App Router API路由统一错误处理方案咨询

我用fetch()调用API路由给仪表盘页面填充数据，开发阶段用try{}catch{}捕获错误，把错误信息写入本地日志文件，服务器统一返回{ok:false}作为错误标识，和未登录等场景响应一致，保证生产服务器的隐蔽性。

示例代码如下：

import { logError } from 'errorLogger';
import { getEncryptedSessionCookie, smartSessionSave } from 'authHandler';

export async function GET(req) {
    try {
        const session = await getEncryptedSessionCookie();
        // 执行一系列任务
        await smartSessionSave(session);
        return Response.json(ret);
    } catch (err) {
        logError('/api/happyLittleRoute',err);
        return Response.json({ok:false});
    }
}

但在生产环境测试Next.js服务器时，构建应用出现如下错误：

/api/happyLittleRoute   Error: Dynamic server usage: Page couldn't be rendered statically because it used `cookies`.

移除try/catch块能消除错误，但没法用logError()记录错误日志，而且服务器会返回服务器错误，满足不了“对外始终表现正常”的要求。我在官方文档只找到页面渲染错误的处理方案，想问有没有合适的方式，给所有GET()和POST()导出函数创建错误边界，实现上述catch块的功能，同时能正常构建并在生产环境运行？

1. 显式标记API路由为动态路由 #

Next.js默认会尝试静态渲染API路由，当你使用cookies这类动态依赖时，必须显式声明该路由为动态。在API路由文件顶部添加以下配置：

export const dynamic = 'force-dynamic';

这样Next.js就不会尝试静态渲染该路由，而是每次请求都在服务器端动态处理，直接解决构建时的动态服务器错误。

2. 封装全局错误处理高阶函数 #

创建一个通用的错误处理包装函数，用来包裹所有API路由的GET/POST方法，统一实现错误捕获、日志记录和返回{ok:false}的逻辑，避免每个路由重复写try/catch：

// utils/apiErrorHandler.js
import { logError } from '../errorLogger';

export const withErrorHandler = (handler) => {
  return async (req) => {
    try {
      return await handler(req);
    } catch (err) {
      // 自动获取当前路由路径并记录错误
      const route = req.nextUrl.pathname;
      logError(route, err);
      return Response.json({ ok: false });
    }
  };
};

然后在API路由中使用这个包装函数：

import { withErrorHandler } from '@/utils/apiErrorHandler';
import { getEncryptedSessionCookie, smartSessionSave } from 'authHandler';

export const GET = withErrorHandler(async (req) => {
  const session = await getEncryptedSessionCookie();
  // 执行一系列任务
  await smartSessionSave(session);
  return Response.json(ret);
});

// POST方法同理
export const POST = withErrorHandler(async (req) => {
  // 业务逻辑代码
});

3. 全局配置动态路由（可选） #

如果你的所有API路由都需要动态处理，可以在next.config.js中全局配置，避免每个文件都单独声明：

/** @type {import('next').NextConfig} */
const nextConfig = {
  // 全局设置所有路由为动态渲染
  dynamic: 'force-dynamic',
};

module.exports = nextConfig;

注意：全局设置会让所有页面都变为动态渲染，若只有API路由需要动态处理，建议还是在单个API路由文件中单独声明export const dynamic = 'force-dynamic';。

关键说明 #

• 显式声明动态路由是解决构建错误的核心，因为Next.js默认静态渲染时无法处理cookies这类请求级别的动态依赖。
• 高阶函数封装可以统一错误处理逻辑，减少重复代码，同时保证所有API路由都能实现错误捕获、日志记录和统一错误响应的需求。

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