Netlify部署React+TypeScript+tRPC前端应用构建失败求助

问题场景 #

使用React + TypeScript技术栈，按tRPC官方文档完成服务端/客户端配置，本地开发运行正常，但部署到Netlify时触发TS2339编译错误，导致构建失败：

8:41:46 AM: TS2339: Property 'createClient' does not exist on type '"useContext collides with a built-in method, you should rename this router or procedure on your backend" | "Provider collides with a built-in method, you should rename this router or procedure on your backend" | "createClient collides with a built-in method, you should rename this router or procedure on your backend..."'.
8:41:46 AM:   Property 'createClient' does not exist on type '"useContext collides with a built-in method, you should rename this router or procedure on your backend"'.
8:41:46 AM:     42 |   const [queryClient] = useState(() => new QueryClient());
8:41:46 AM:     43 |   const [trpcClient] = useState(() =>
8:41:46 AM:   > 44 |     trpc.createClient({
8:41:46 AM:        |          ^^^^^^^^^^^^
8:41:46 AM:     45 |       links: [
8:41:46 AM:     46 |         httpBatchLink({
8:41:46 AM:     47 |           url: `${process.env.REACT_APP_BACKEND_URL}/trpc`,
8:41:46 AM: ​
8:41:46 AM:   "build.command" failed        

客户端代码片段（App.tsx）：

export default function App() {
  const [queryClient] = useState(() => new QueryClient());
  const [trpcClient] = useState(() =>
    trpc.createClient({
      links: [
        httpBatchLink({
          url: `${process.env.REACT_APP_BACKEND_URL}/trpc`,
        }),
      ],
    })
  );

  return (
    <trpc.Provider client={trpcClient} queryClient={queryClient}>
      <QueryClientProvider client={queryClient}>    
        {/* 其他代码 */}
      </QueryClientProvider>
    </trpc.Provider>
  );
}

错误原因 #

核心问题是后端tRPC路由中定义了与tRPC客户端内置方法重名的Procedure/Router。

从错误提示字符串（useContext collides with a built-in method...）能看出，你的后端存在命名冲突的路由——比如可能定义了useContext、Provider或createClient这类名称的Procedure，而这些名称和tRPC客户端的内置API（如trpc.createClient、trpc.Provider）完全重名。

tRPC的类型系统检测到这种冲突时，会返回错误提示字符串替代原本的客户端类型，导致客户端调用trpc.createClient时，TypeScript认为当前trpc的类型是错误提示文本，自然找不到createClient属性。

本地开发时可能因类型检查严格度低（比如tsconfig.json的strict设为false）或开发服务器未触发完整校验，问题未暴露；而Netlify构建时会强制执行严格类型检查，因此报错。

解决方案 #

1. 排查后端路由命名
   检查后端tRPC Router代码，找出所有和tRPC客户端内置API重名的Procedure/Router，比如：useContext、Provider、createClient、useQuery、useMutation等，这些都是客户端内置方法，不能作为自定义路由名称。

2. 重命名冲突路由
   将冲突的Procedure/Router改成不重复的名称，比如把createClient改为createAppClient，把useContext改为useAppContext。

3. 验证类型修复
   修改后端代码后，重新导出tRPC路由类型，确保客户端能获取最新类型，然后在本地运行：

   tsc --noEmit
   

   确认类型错误已修复。

4. 重新部署
   把修复后的代码推送到仓库，触发Netlify重新构建即可解决问题。

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