Next.js 中处理 401 未授权错误的优雅方案

在 Next.js 项目中，当使用服务器端数据获取时，处理 401 未授权错误是一个常见但棘手的问题。本文将深入探讨如何优雅地解决这个问题，特别是当与 auth.js 身份验证库结合使用时。

问题背景

在服务器端数据获取过程中，当 API 返回 401 状态码时，通常意味着用户的会话已过期或无效。理想情况下，我们希望自动将用户登出并重定向到登录页面。然而，在 Next.js 的服务器组件中直接修改 cookie 会遇到技术限制。

核心挑战

Next.js 的设计原则要求在服务器组件中不能直接修改 cookie。当尝试在 fetch 拦截器中调用 signOut 方法时，会遇到"Cookies can only be modified in a Server Action or Route Handler"的错误提示。这是 Next.js 的安全机制，确保 cookie 操作只在特定上下文中进行。

解决方案架构

经过实践验证，最可靠的解决方案是采用路由处理器(Route Handler)模式。具体实现分为两个关键部分：

1. 增强型 fetch 封装：创建一个智能的 fetch 包装器，能够识别 401 错误
2. 专用登出路由：建立一个专门处理登出逻辑的 API 端点

实现细节

1. 增强型 fetch 封装

创建一个名为 fetchApiProxy 的高阶函数，它包装了基础的 fetch 功能并添加了错误处理逻辑。当检测到 401 状态码时，它会触发重定向到专门的登出路由。

这个封装具有以下特点：

• 自动携带认证令牌
• 统一错误处理格式
• 401 错误特殊处理
• 类型安全的响应结构

2. 登出路由处理器

创建一个 GET 路由处理器，专门处理登出逻辑。这个处理器执行以下操作：

• 清除所有相关的认证 cookie
• 调用 auth.js 的 signOut 方法
• 执行重定向到登录页面

这种分离关注点的设计既遵守了 Next.js 的约束，又提供了清晰的逻辑流程。

技术要点

1. cookie 处理：在路由处理器中，使用 next/headers 的 cookies() 方法安全地操作 cookie
2. 重定向机制：使用 NextResponse.redirect 实现服务器端重定向
3. 错误传播：保持原始 fetch 的错误信息，便于调试
4. 会话管理：正确处理 auth.js 的会话状态

最佳实践建议

1. 统一错误处理：在整个应用中保持一致的错误处理模式
2. 安全考虑：确保登出路由不暴露敏感信息
3. 性能优化：避免不必要的重定向
4. 可测试性：设计易于测试的独立模块

总结

这种解决方案不仅解决了技术限制问题，还提供了一个可扩展的架构模式。它展示了如何在框架约束下设计出既安全又优雅的解决方案，值得在类似的 Next.js 项目中推广应用。

对于开发者而言，理解并应用这种模式可以显著提升应用的健壮性和用户体验，特别是在处理敏感的身份验证流程时。