在Next.js中解决openapi-fetch与React Query的headers()报错问题

在使用Next.js、React Query和openapi-fetch构建现代Web应用时，开发者可能会遇到一个棘手的错误："Invariant: headers() expects to have requestAsyncStorage, none available"。这个问题源于Next.js应用路由(App Router)架构下服务器组件与客户端组件的边界处理不当。

问题本质分析

这个错误通常发生在以下场景：

1. 在客户端组件中直接使用openapi-fetch客户端
2. 中间件中调用了仅限服务器端使用的API（如auth()）
3. 环境变量未正确配置为客户端可用

核心原因是openapi-fetch的中间件逻辑试图在浏览器环境中访问仅服务器端可用的headers()方法，而Next.js的安全机制阻止了这种行为。

解决方案对比

开发者有两种主要解决路径：

方案一：改造客户端使其完全在浏览器运行

• 移除中间件中的服务器端专用逻辑
• 确保所有环境变量以NEXT_PUBLIC_前缀暴露
• 可能需要重构认证流程

方案二：保持服务器端数据获取

• 将数据获取逻辑移至服务器动作(Server Actions)
• 通过React Query的prefetchQuery或常规queryFn调用
• 更适合需要代理请求或额外处理的场景

推荐实现方案

基于项目实际情况，推荐采用方案二的混合架构：

1. 创建专用的服务器动作文件(actions.ts)：

"use server";

export async function getConfigProperties() {
  const { data, error } = await client.GET("/api/settings/config-properties");
  return { data, error };
}

2. 在客户端组件中通过React Query调用：

"use client";

const { data, isPending, isError, error } = useQuery({
  queryKey: ["getConfigProperties"],
  queryFn: async () => {
    const { data, error } = await getConfigProperties();
    if (error) throw new Error(error.message);
    return data;
  },
});

架构优势

这种设计带来了几个关键好处：

• 清晰的关注点分离：数据获取逻辑保留在服务器端
• 更好的错误处理：可以在客户端自定义错误展示
• 符合Next.js最佳实践：充分利用服务器组件能力
• 安全性：敏感逻辑和凭证不会暴露到客户端

注意事项

1. 性能考量：这种架构会在Vercel等托管平台上产生额外的边缘请求
2. 类型安全：确保服务器动作返回类型与客户端期望匹配
3. 错误边界：建议在组件层面添加错误边界处理
4. 缓存策略：合理配置React Query的缓存参数优化性能

通过这种架构设计，开发者可以充分利用openapi-fetch的类型安全特性，同时遵循Next.js的应用路由最佳实践，构建出既健壮又易于维护的现代Web应用。