Next.js客户端组件用Urql报错TypeError: t.executeQuery is not a function求因

环境假设 #

• Node.js 20.14.0
• Next.js 14.2.3
• urql 4.1.0
• @urql/core 5.0.4
• @urql/next 1.1.1

核心问题 #

在Next.js客户端组件中使用Urql时触发错误：TypeError: t.executeQuery is not a function，相关代码如下：

export function useGetEventByIdQuery(options: Omit<Urql.UseQueryArgs<Operations.GetEventByIdQueryVariables>, 'query'>) {
  return Urql.useQuery<Operations.GetEventByIdQuery, Operations.GetEventByIdQueryVariables>({ query: Operations.GetEventByIdDocument, ...options });
};

const [data] = useGetEventByIdQuery({ variables: { id: params.id } });

问题成因 #

这个错误源于版本不兼容：urql 4.x与@urql/core 5.x的API存在冲突。@urql/core 5.x重构了核心查询执行逻辑，移除了executeQuery方法，但urql 4.x的上层依赖（如@urql/next）仍在调用该已被移除的方法，导致类型错误。

另外，代码中直接通过全局Urql.useQuery调用的方式，未正确使用@urql/next为Next.js适配的查询钩子，进一步加剧了版本不匹配带来的问题。

解决方向 #

• API修复：
  从@urql/next导入适配Next.js的useQuery钩子，替代全局Urql对象的调用，调整后的代码示例：

  import { useQuery } from '@urql/next';
  
  export function useGetEventByIdQuery(options: Omit<UseQueryArgs<Operations.GetEventByIdQueryVariables>, 'query'>) {
    return useQuery<Operations.GetEventByIdQuery, Operations.GetEventByIdQueryVariables>({ query: Operations.GetEventByIdDocument, ...options });
  };
  

• 版本对齐：
  将urql与@urql/core的版本统一，要么同时升级到5.x，要么将@urql/core降级至4.x版本（与urql 4.1.0匹配），消除跨版本API差异。

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