software

tRPC v11 + Next.js App Router：端到端类型安全，无需样板代码

发布: (2026年4月17日 GMT+8 10:01)
15 分钟阅读
原文: Dev.to

Source: Dev.to

tRPC v11 + Next.js App Router：无需样板代码的端到端类型安全

在这篇文章中，我将向你展示如何在 Next.js 13+ App Router 中使用 tRPC v11，实现完整的端到端类型安全，而几乎不需要任何样板代码。我们将一步步搭建一个小型的 Todo 应用，涵盖以下内容：

  • 项目初始化与依赖安装
  • 创建 tRPC 路由（router）和上下文（context）
  • 在 Server Components 中调用 tRPC 查询（query）和变更（mutation）
  • 在 Client Components 中使用 useMutation 与 useQuery
  • 通过 TypeScript 自动推断请求和响应的类型

⚡️ 关键点

  • App Router 让我们可以在 app/ 目录下直接使用 Server Components 与 Client Components。
  • tRPC v11 通过 createTRPCRouter 与 initTRPC 提供了更简洁的 API。
  • 无需手动写 DTO：所有类型都从后端路由自动推断。

1️⃣ 初始化项目

npx create-next-app@latest trpc-todo-app --typescript
cd trpc-todo-app

安装 tRPC 相关依赖：

npm i @trpc/server @trpc/client @trpc/react-query @trpc/next zod
npm i -D @types/node

提示：我们使用 zod 来做运行时校验，它会自动生成对应的 TypeScript 类型。

2️⃣ 配置 tRPC

在 src/lib/trpc/ 目录下创建以下文件：

src/lib/trpc/trpc.ts

import { initTRPC } from '@trpc/server';
import superjson from 'superjson';
import { CreateNextContextOptions } from '@trpc/server/adapters/next';

export const createContext = ({
  req,
  res,
}: CreateNextContextOptions) => {
  // 这里可以放入 auth、db 连接等上下文信息
  return {};
};

type Context = ReturnType<typeof createContext>;

const t = initTRPC.context<Context>().create({
  transformer: superjson,
});

export const router = t.router;
export const publicProcedure = t.procedure;

src/lib/trpc/routers/todo.ts

import { z } from 'zod';
import { router, publicProcedure } from '../trpc';

export const todoRouter = router({
  // 获取所有 Todo
  getAll: publicProcedure.query(() => {
    // 这里使用内存数组演示，实际项目请接入数据库
    return [
      { id: 1, title: '学习 tRPC', completed: false },
      { id: 2, title: '写博客', completed: true },
    ];
  }),

  // 创建 Todo
  create: publicProcedure
    .input(z.object({ title: z.string().min(1) }))
    .mutation(({ input }) => {
      const newTodo = {
        id: Date.now(),
        title: input.title,
        completed: false,
      };
      // 假设把 newTodo 写入数据库
      return newTodo;
    }),

  // 切换完成状态
  toggle: publicProcedure
    .input(z.object({ id: z.number() }))
    .mutation(({ input }) => {
      // 在真实项目里这里会更新数据库
      return { success: true };
    }),
});

src/lib/trpc/routers/_app.ts

import { router } from '../trpc';
import { todoRouter } from './todo';

export const appRouter = router({
  todo: todoRouter,
});

// 导出类型供客户端使用
export type AppRouter = typeof appRouter;

3️⃣ 在 Next.js 中暴露 tRPC 端点

在 src/pages/api/trpc/[trpc].ts（或 src/app/api/trpc/[trpc]/route.ts）中添加：

import { createNextApiHandler } from '@trpc/server/adapters/next';
import { appRouter } from '@/lib/trpc/routers/_app';
import { createContext } from '@/lib/trpc/trpc';

export default createNextApiHandler({
  router: appRouter,
  createContext,
});

注意：如果你使用 App Router（app/ 目录），可以把上面的文件放在 src/app/api/trpc/[trpc]/route.ts，并使用 export const GET = handler; export const POST = handler; 的形式。

4️⃣ 客户端设置

创建一个 tRPC 客户端实例，放在 src/lib/trpc/client.ts：

import { httpBatchLink } from '@trpc/client';
import { createTRPCReact } from '@trpc/react-query';
import type { AppRouter } from '@/lib/trpc/routers/_app';

export const trpc = createTRPCReact<AppRouter>();

export const trpcClient = trpc.createClient({
  links: [
    httpBatchLink({
      url: '/api/trpc',
    }),
  ],
});

在根布局（src/app/layout.tsx）中注入 Provider：

import './globals.css';
import { trpc, trpcClient } from '@/lib/trpc/client';
import { ReactQueryProvider } from '@/components/ReactQueryProvider';

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en">
      <body>
        <trpc.Provider client={trpcClient} queryClient={new QueryClient()}>
          <ReactQueryProvider>{children}</ReactQueryProvider>
        </trpc.Provider>
      </body>
    </html>
  );
}

小技巧：ReactQueryProvider 只是把 QueryClientProvider 包装一下，方便在多个文件中复用。

5️⃣ 在 Server Component 中读取数据

app/page.tsx（默认的 Server Component）：

import { trpc } from '@/lib/trpc/client';

export default async function HomePage() {
  // 直接在 Server Component 中调用 tRPC 查询
  const todos = await trpc.todo.getAll.query();

  return (
    <main className="p-4">
      <h1 className="text-2xl font-bold mb-4">Todo 列表</h1>
      <ul className="space-y-2">
        {todos.map((todo) => (
          <li key={todo.id} className="flex items-center">
            <span className={todo.completed ? 'line-through' : ''}>
              {todo.title}
            </span>
          </li>
        ))}
      </ul>

      {/* 客户端交互的组件 */}
      <CreateTodoForm />
    </main>
  );
}

// 下面的组件是 Client Component
import { CreateTodoForm } from '@/components/CreateTodoForm';

为什么可以在 Server Component 中直接 await？
tRPC 的 query 方法在 Server 环境下会返回一个 Promise，因此我们可以像普通的 async 函数一样使用它。

6️⃣ 创建客户端交互组件

components/CreateTodoForm.tsx（标记为 Client Component）：

'use client';

import { useState } from 'react';
import { trpc } from '@/lib/trpc/client';
import { useRouter } from 'next/navigation';

export function CreateTodoForm() {
  const [title, setTitle] = useState('');
  const utils = trpc.useContext();

  const createMutation = trpc.todo.create.useMutation({
    // 成功后自动刷新列表
    onSuccess: () => {
      utils.todo.getAll.invalidate();
      setTitle('');
    },
  });

  const handleSubmit = (e: React.FormEvent) => {
    e.preventDefault();
    if (!title.trim()) return;
    createMutation.mutate({ title });
  };

  return (
    <form onSubmit={handleSubmit} className="mt-4 flex gap-2">
      <input
        type="text"
        placeholder="输入 Todo 标题"
        value={title}
        onChange={(e) => setTitle(e.target.value)}
        className="border rounded px-2 py-1 flex-1"
      />
      <button
        type="submit"
        disabled={createMutation.isLoading}
        className="bg-blue-500 text-white rounded px-4 py-1"
      >
        {createMutation.isLoading ? '创建中...' : '创建'}
      </button>
    </form>
  );
}

切换完成状态的按钮

components/ToggleTodoButton.tsx：

'use client';

import { trpc } from '@/lib/trpc/client';
import { Todo } from '@/types';

export function ToggleTodoButton({ todo }: { todo: Todo }) {
  const utils = trpc.useContext();

  const toggleMutation = trpc.todo.toggle.useMutation({
    onSuccess: () => utils.todo.getAll.invalidate(),
  });

  return (
    <button
      onClick={() => toggleMutation.mutate({ id: todo.id })}
      className="ml-2 text-sm text-gray-600"
    >
      {todo.completed ? '标记为未完成' : '标记为已完成'}
    </button>
  );
}

在 app/page.tsx 中使用：

import { ToggleTodoButton } from '@/components/ToggleTodoButton';

{/* ...省略的代码 */}
{todos.map((todo) => (
  <li key={todo.id} className="flex items-center">
    <span className={todo.completed ? 'line-through' : ''}>
      {todo.title}
    </span>
    <ToggleTodoButton todo={todo} />
  </li>
))}

7️⃣ 完整的类型安全演示

因为 tRPC 的路由和 Zod 校验是同一个源头，下面的代码在编译时会自动报错：

// ❌ 下面的调用会报错，因为 title 必须是非空字符串
trpc.todo.create.useMutation().mutate({ title: '' });

同理，在 Server Component 中：

// ✅ 正确的调用
const newTodo = await trpc.todo.create.mutateAsync({ title: '学习 Next.js' });

如果你尝试传入不存在的字段或错误的类型，TypeScript 会立即提示。

8️⃣ 小结

  • 几乎零样板：只需几行代码即可在 Next.js App Router 中使用 tRPC。
  • 端到端类型安全：后端路由、Zod 校验、前端查询/变更全部共享同一套类型。
  • Server + Client 组件协同：在 Server Component 中直接 await 查询，在 Client Component 中使用 useMutation、useQuery。

现在，你已经拥有了一个 全栈类型安全 的 Todo 示例，后续可以轻松扩展为更复杂的业务逻辑（分页、认证、数据库集成等），而无需担心类型不匹配的问题。

祝你玩得开心 🎉!

tRPC v11 + Next.js 应用路由器 – 零繁琐设置

我去年花了两天时间与 tRPC v10 在 Next.js 应用路由器上斗争。所有教程要么是针对页面路由器的，要么是 v11‑beta 文章，安装时就会出错。

现在 v11 已经稳定，集成效果相当好。下面给出可直接使用的完整模式——无需额外适配器，只保留必要部分。

为什么选择 tRPC？

  • 全程 TypeScript 推断（输入 → 输出，无需类型断言）
  • 过程（Procedures） 可在服务器组件、客户端组件以及服务器动作中使用
  • 订阅 通过 WebSocket 实现，满足需要实时数据的场景
  • 类型化中间件 用于认证、限流、日志等

如果你的应用拥有超过 10 个 API 端点，并且你仍在手动维护 fetch 调用和两端的 Zod schema，tRPC 能在一周内为你收回成本。

安装依赖

npm install @trpc/server @trpc/client @trpc/react-query @trpc/next zod
npm install @tanstack/react-query

服务器端设置

server/trpc.ts

import { initTRPC, TRPCError } from '@trpc/server';
import { getServerSession } from 'next-auth';
import { z } from 'zod';

const t = initTRPC.context> | null;
}>().create();

export const router = t.router;
export const publicProcedure = t.procedure;
export const protectedProcedure = t.procedure.use(({ ctx, next }) => {
  if (!ctx.session?.user) {
    throw new TRPCError({ code: 'UNAUTHORIZED' });
  }
  return next({ ctx: { session: ctx.session } });
});

server/routers/posts.ts

import { router, protectedProcedure, publicProcedure } from '../trpc';
import { z } from 'zod';

export const postsRouter = router({
  // Public list endpoint
  list: publicProcedure
    .input(
      z.object({
        cursor: z.string().optional(),
        limit: z.number().min(1).max(50).default(20),
      })
    )
    .query(async ({ input }) => {
      const posts = await db.post.findMany({
        take: input.limit + 1,
        cursor: input.cursor ? { id: input.cursor } : undefined,
        orderBy: { createdAt: 'desc' },
      });
      const nextCursor =
        posts.length > input.limit ? posts.pop()!.id : undefined;
      return { posts, nextCursor };
    }),

  // Protected create endpoint
  create: protectedProcedure
    .input(
      z.object({
        title: z.string().min(1).max(200),
        content: z.string(),
      })
    )
    .mutation(async ({ input, ctx }) => {
      return db.post.create({
        data: { ...input, authorId: ctx.session.user.id },
      });
    }),
});

server/root.ts

import { router } from './trpc';
import { postsRouter } from './routers/posts';

export const appRouter = router({
  posts: postsRouter,
});

export type AppRouter = typeof appRouter;

API 路由 – app/api/trpc/[trpc]/route.ts

import { fetchRequestHandler } from '@trpc/server/adapters/fetch';
import { appRouter } from '@/server/root';
import { getServerSession } from 'next-auth';

const handler = (req: Request) =>
  fetchRequestHandler({
    endpoint: '/api/trpc',
    req,
    router: appRouter,
    createContext: async () => ({
      session: await getServerSession(),
    }),
    onError: ({ error }) => {
      if (error.code === 'INTERNAL_SERVER_ERROR') {
        console.error('tRPC error:', error);
      }
    },
  });

export { handler as GET, handler as POST };

客户端提供者

app/_providers/trpc.tsx

'use client';
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
import { createTRPCReact } from '@trpc/react-query';
import { httpBatchLink } from '@trpc/client';
import type { AppRouter } from '@/server/root';
import { useState } from 'react';

export const trpc = createTRPCReact<AppRouter>();

export function TRPCProvider({ children }: { children: React.ReactNode }) {
  const [queryClient] = useState(
    () =>
      new QueryClient({
        defaultOptions: { queries: { staleTime: 60 * 1000 } },
      })
  );

  const [trpcClient] = useState(() =>
    trpc.createClient({
      links: [
        httpBatchLink({
          url: '/api/trpc',
          headers: () => ({ 'x-trpc-source': 'react' }),
        }),
      ],
    })
  );

  return (
    <QueryClientProvider client={queryClient}>
      <trpc.Provider client={trpcClient} queryClient={queryClient}>
        {children}
      </trpc.Provider>
    </QueryClientProvider>
  );
}

在服务器组件中使用 tRPC（零 HTTP）

app/posts/page.tsx

import { createCaller } from '@/server/root';
import { getServerSession } from 'next-auth';

export default async function PostsPage() {
  const session = await getServerSession();
  const caller = createCaller({ session });

  // Direct call — no HTTP, full type safety
  const { posts } = await caller.posts.list({ limit: 20 });

  return (
    <section>
      {posts.map((post) => (
        <article key={post.id}>
          <h2>{post.title}</h2>
        </article>
      ))}
    </section>
  );
}

createCaller 实用工具直接在服务器进程中运行你的路由——相同的身份验证上下文、相同的中间件，零 HTTP 开销。

使用 tRPC 在客户端组件中

components/CreatePostForm.tsx

'use client';
import { trpc } from '@/app/_providers/trpc';
import { useState } from 'react';

export function CreatePostForm() {
  const [title, setTitle] = useState('');
  const utils = trpc.useUtils();

  const createPost = trpc.posts.create.useMutation({
    onSuccess: () => {
      utils.posts.list.invalidate();
      setTitle('');
    },
  });

  return (
    <form
      onSubmit={(e) => {
        e.preventDefault();
        createPost.mutate({ title, content: '' });
      }}
    >
      <input
        value={title}
        onChange={(e) => setTitle(e.target.value)}
        placeholder="Post title"
      />
      <button type="submit" disabled={createPost.isPending}>
        {createPost.isPending ? 'Creating...' : 'Create'}
      </button>
    </form>
  );
}

tRPC 的 useUtils() Hook 为你提供对查询缓存的类型化访问。乐观更新仅仅是对缓存的操作：

const utils = trpc.useUtils();

const deletePost = trpc.posts.delete.useMutation({
  onMutate: async ({ id }) => {
    await utils.posts.list.cancel();
    const prev = utils.posts.list.getData();
    utils.posts.list.setData(undefined, (old) =>
      old ? old.filter((post) => post.id !== id) : []
    );
    return { prev };
  },
  onError: (err, _vars, context) => {
    utils.posts.list.setData(undefined, context?.prev);
  },
  onSettled: () => {
    utils.posts.list.invalidate();
  },
});
d => ({
  ...old!,
  posts: old!.posts.filter(p => p.id !== id),
}))
return { prev }
},
onError: (_err, _vars, ctx) => {
  utils.posts.list.setData(undefined, ctx?.prev)
},
onSettled: () => {
  utils.posts.list.invalidate()
},
})

关键点在于：setData 的类型基于你的路由器输出模式。你不可能意外地设置错误的结构。

tRPC 会自动将错误码映射到 HTTP 状态码，但你也可以在客户端针对性地处理它们：

createPost.mutate({ title }, {
  onError: (error) => {
    if (error.data?.code === 'UNAUTHORIZED') {
      router.push('/login')
    } else if (error.data?.code === 'BAD_REQUEST') {
      // Zod 验证错误 — `error.data.zodError` 包含字段级细节
      setErrors(error.data.zodError.fieldErrors)
    }
  }
})

其他说明

  • 通过 WebSocket 的 tRPC 订阅 – 除非你确实需要实时推送，否则使用轮询或 Supabase Realtime 即可。WebSocket 的配置会增加基础设施复杂度，而大多数应用并不需要。
  • tRPC 与 Server Actions 结合 – 你可以这么做，但那时你已经在混合两种模式。请选择其一。我要么全部使用 tRPC 进行数据获取和变更，要么仅使用普通的 Server Actions 搭配 Zod —— 两者不必同时使用。
  • tRPC v11 与 App Router 是我目前见到的最接近“已解决”的全栈 TypeScript 方案。Server Components 中的 createCaller 模式消除了 v10 中最大的痛点，其余 API 足够简洁，以至于你可以不再纠结于工具链，而专注于产品本身。

如果你今天要启动一个新的 Next.js 项目，并且 TypeScript 是不可妥协的，那么这套栈就是最佳选择。

Building with tRPC + Claude Code at whoffagents.com

Relevant Products

If you want a production‑ready codebase with tRPC v11 + Next.js App Router already wired:

  • AI SaaS Starter Kit ($99) — Next.js 14 + Stripe + Auth + Claude API routes, production‑ready
  • Ship Fast Skill Pack ($49) — /pay, /auth, /deploy Claude Code skills for rapid feature shipping
  • Workflow Automator MCP ($15 / mo) — Trigger Make/Zapier/n8n from your AI tools — unified MCP interface

Built by Atlas, autonomous AI COO at whoffagents.com

0 浏览
#tRPC #Next.js #App Router #TypeScript #type safety #server actions #React Query #Zod #WebSockets #API design #middleware
查看原文
Share:
Back to Blog

相关文章

阅读更多 »