Next.js SaaS Starter项目中解决Monorepo下Cookie授权问题

在Next.js SaaS Starter项目中，当开发者尝试将认证模块从lib/auth迁移到packages/auth时，可能会遇到一个常见问题：cookies在请求范围外被调用的错误。这个问题通常出现在Monorepo架构中，特别是当多个包需要共享认证逻辑时。

问题现象

开发者会遇到如下错误提示："cookies was called outside a request scope"。这个错误表明系统尝试在请求上下文之外访问cookies，这在Next.js应用中是不被允许的。错误通常会导致TRPC客户端出现"Invalid response or stream interrupted"的异常。

问题根源

这个问题的本质在于Next.js的cookies API设计。Next.js要求所有与cookies相关的操作必须在请求处理函数的上下文中执行。当我们将认证逻辑提取到独立的包中时，如果处理不当，就可能导致cookies访问脱离了正确的请求上下文。

解决方案

解决这个问题的关键在于确保cookies访问始终在正确的请求上下文中进行。具体实现方式如下：

1. 重构TRPC路由处理器：需要重新设计/api/trpc/[trpc]/route.ts中的handler函数，确保认证逻辑在正确的上下文中执行。

2. 上下文传递：将请求上下文显式地传递给认证模块，而不是让认证模块直接访问全局的cookies API。

3. 依赖注入：考虑使用依赖注入的方式，将cookies访问器作为参数传递给认证函数。

实现建议

以下是一个改进后的代码结构示例：

// 在TRPC路由处理器中
export async function POST(req: NextRequest) {
  // 获取请求上下文中的cookies
  const cookies = req.cookies;
  
  // 将cookies传递给认证模块
  const session = await getSession({ cookies });
  
  // 创建TRPC上下文
  const ctx = {
    session,
    // 其他上下文
  };
  
  // 创建TRPC处理器
  const handler = createNextApiHandler({
    router: appRouter,
    createContext: () => ctx,
  });
  
  return handler(req);
}

最佳实践

1. 避免直接依赖全局API：在共享模块中尽量避免直接使用像cookies这样的请求相关API。

2. 显式依赖：通过参数传递所有需要的依赖，使函数的行为更加可预测。

3. 上下文隔离：确保每个请求都有自己独立的上下文，避免状态共享。

4. 类型安全：使用TypeScript确保所有依赖都正确传递，减少运行时错误。

总结

在Monorepo架构下共享认证逻辑时，正确处理请求上下文是关键。通过重构代码结构，显式传递依赖，可以避免cookies访问超出请求范围的问题。这种方法不仅解决了当前问题，还使代码更加模块化和可测试，为项目长期维护打下良好基础。

对于使用Next.js SaaS Starter的开发者来说，理解这种上下文管理机制尤为重要，特别是在构建需要认证的企业级应用时。正确的架构设计可以显著提高应用的稳定性和可维护性。