接口字段从 camelCase 悄悄变成 snake_case、返回结构中的数字突然被序列化成字符串，这类问题通常不会在构建阶段暴露，而是等到页面运行时才以报错或白屏的形式出现。tRPC 给 Vue 3 项目提供了一种不同的思路：把后端的路由定义视为唯一契约，让 TypeScript 类型从服务端自动流入前端组件。调用远程过程不再需要手写 URL、方法、查询参数和返回值类型，编译器会在你写错字段名的第一时间给出提示。对维护中大型后台、B 端系统或全栈 TypeScript 项目的团队来说，这种端到端类型安全能显著降低接口联调成本。
下面结合一个实际的 Vue 3 + tRPC 工程，聊聊它的实现原理、搭建方式和生产环境需要注意的细节。
从类型漂移说起：tRPC 与 REST、GraphQL 的差异
传统 REST 接口的契约通常由文档、Swagger 或口头约定维护。服务端修改字段类型或路径后，如果文档没有同步，前端往往只能通过运行时报错来发现。即便使用 OpenAPI 生成类型，也需要额外的构建步骤和工具链，生成结果的时效性也依赖开发者的执行时机。
tRPC 改变了这种协作方式。它允许你直接在服务端用 TypeScript 定义输入输出结构，并把整个路由对象的类型导出给前端。前端通过 Proxy 客户端调用后端方法，所有参数、返回值、错误类型都由编译器推导。与 GraphQL 相比，tRPC 不需要引入新的查询语言和 schema 文件，也不需要在客户端拼接 query 字符串；对 REST 来说，tRPC 提供了更自然的函数调用体验。
| 维度 | REST | GraphQL | tRPC |
|---|---|---|---|
| 契约维护 | 文档或 OpenAPI | Schema 文件 | 后端 TypeScript 类型 |
| 调用方式 | HTTP + URL + Method | Query 字符串 | 函数调用 |
| 类型推导 | 需要生成工具 | 需要 codegen | 直接共享类型 |
| 适合场景 | 跨语言、第三方集成 | 复杂聚合、按需取数 | 全栈 TS 内部系统 |
先看一个最小的服务端路由。tRPC 使用 zod 做运行时输入校验，同时推导出 TypeScript 类型：
import { initTRPC } from '@trpc/server';
import { z } from 'zod';
const t = initTRPC.create();
export const router = t.router;
export const publicProcedure = t.procedure;
export const appRouter = router({
greeting: publicProcedure
.input(z.object({ name: z.string() }))
.query(({ input }) => {
return {
message: `Hello, ${input.name}!`,
};
}),
});
export type AppRouter = typeof appRouter;
这段代码的核心是 AppRouter 类型。前端只要拿到这个类型，后续调用 trpc.greeting.query 时，编辑器就能知道参数必须包含 name，返回值一定是 { message: string }。这是 tRPC 与普通 axios 封装最本质的区别。
用 pnpm workspace 搭建 Vue 3 与 tRPC 工程
工程化落地时，最常见的是前后端放在同一个 monorepo 中。这样做的好处是前端可以直接通过 TypeScript 项目引用导入服务端的 AppRouter，不需要发布私有 npm 包。这里推荐使用 pnpm workspace 管理依赖，目录结构可以设计为 packages/server、packages/web 和 packages/shared。
packages: - 'packages/*'
服务端需要安装 @trpc/server、zod 以及适配器，比如 @trpc/server/adapters/express。下面是一个带 Express 的完整入口示例：
import express from 'express';
import cors from 'cors';
import { createExpressMiddleware } from '@trpc/server/adapters/express';
import { appRouter } from './router';
const app = express();
app.use(cors({ origin: 'http://localhost:5173', credentials: true }));
app.use(
'/trpc',
createExpressMiddleware({
router: appRouter,
createContext: ({ req, res }) => {
return {
req,
res,
user: null,
};
},
}),
);
app.listen(3000, () => {
console.log('tRPC server running at http://localhost:3000/trpc');
});
注意这里出现了箭头函数 =>，在代码块渲染时 > 需要转义。实际文件内容仍是 =>。服务端启动后，tRPC 默认监听 /trpc 路径，所有查询和变更都会通过 HTTP POST 发送到这个端点。
前端 web 包中先安装 @trpc/client。创建客户端时，推荐使用 httpBatchLink，它会把短时间内的多个调用合并成一个 HTTP 请求，减少网络开销。客户端需要从服务端导入 AppRouter 类型，这个过程通过 TypeScript 的 paths 配置或 workspace 内部的源码引用完成。
import { createTRPCProxyClient, httpBatchLink } from '@trpc/client';
import type { AppRouter } from '@your/server';
export const trpc = createTRPCProxyClient<AppRouter>({
links: [
httpBatchLink({
url: import.meta.env.VITE_TRPC_URL ?? 'http://localhost:3000/trpc',
headers: () => {
const token = localStorage.getItem('token');
return token ? { Authorization: `Bearer ${token}` } : {};
},
}),
],
});
这里的 createTRPCProxyClient<AppRouter> 是类型参数，因此代码块中的 < 和 > 也必须写成实体。配置完成后，组件的任何地方都可以直接使用这个 trpc 对象发起请求。
在 Vue 3 组件里把 tRPC 封装成组合式函数
虽然可以直接在 <script setup> 中调用 trpc.greeting.query()，但在真实项目中更建议封装一层组合式函数。组合式函数可以把 loading、error、data 以及重试逻辑集中管理，避免每个页面重复编写异步状态。
下面是获取文章列表的组合式函数。利用 inferRouterOutputs 可以精确推导后端 post.list 路由的返回类型，不需要手动维护 interface：
import { ref, onMounted } from 'vue';
import { trpc } from '../api/trpc';
import type { AppRouter } from '@your/server';
import type { inferRouterOutputs } from '@trpc/server';
type PostListOutput = inferRouterOutputs<AppRouter>['post']['list'];
export function usePostList() {
const posts = ref<PostListOutput>([]);
const loading = ref(false);
const error = ref<unknown>(null);
async function load() {
loading.value = true;
error.value = null;
try {
posts.value = await trpc.post.list.query();
} catch (err) {
error.value = err;
} finally {
loading.value = false;
}
}
onMounted(load);
return {
posts,
loading,
error,
reload: load,
};
}
在组件中使用这个组合式函数时，posts.value 会保留完整的对象结构。如果你把后端返回的 id 从 number 改成 string，前端在使用 post.id 时会立即出现类型错误，而不是等到请求回来后再排查。
<script setup lang="ts">
import { usePostList } from './composables/usePostList';
const { posts, loading, error, reload } = usePostList();
</script>
<template>
<section>
<button @click="reload">刷新列表</button>
<div v-if="loading">加载中...</div>
<div v-else-if="error">请求失败：{{ error }}</div>
<ul v-else>
<li v-for="post in posts" :key="post.id">{{ post.title }}</li>
</ul>
</section>
</template>
如果项目里已经有 TanStack Query，可以直接使用 @tanstack/vue-query 配合 tRPC 的 vanilla client 手动调用，既保留缓存能力，又能获得类型推导。更简单的做法是继续使用上面的组合式函数，如果数据请求不复杂，完全够用。
生产环境必须解决的鉴权、错误处理与跨域细节
tRPC 本身不限制鉴权方式，通常在后端的 createContext 中根据请求头解析用户，再通过中间件保护需要登录的路由。下面是一个基于 Bearer Token 的简化示例：
import { initTRPC, TRPCError } from '@trpc/server';
import type { CreateExpressContextOptions } from '@trpc/server/adapters/express';
export async function createContext({ req }: CreateExpressContextOptions) {
const auth = req.headers.authorization ?? '';
const token = auth.startsWith('Bearer ') ? auth.slice(7) : null;
const user = token ? await verifyToken(token) : null;
return { user };
}
const t = initTRPC.context<{ user: User | null }>().create();
const isAuthed = t.middleware(({ next, ctx }) => {
if (!ctx.user) {
throw new TRPCError({ code: 'UNAUTHORIZED' });
}
return next({
ctx: {
user: ctx.user,
},
});
});
export const protectedProcedure = t.procedure.use(isAuthed);
上面代码中的 initTRPC.context<{ user: User | null }>() 含有类型参数，在 HTML 代码块中同样需要转义。前端触发受保护路由时，如果请求头缺少 token，会收到 UNAUTHORIZED 错误。Vue 组件里可以使用 TRPCClientError 做统一判断：
import { TRPCClientError } from '@trpc/client';
async function safeLoad() {
try {
await trpc.account.profile.query();
} catch (err) {
if (err instanceof TRPCClientError) {
console.log(err.meta, err.shape?.message);
if (err.data?.code === 'UNAUTHORIZED') {
router.push('/login');
}
}
}
}
跨域问题是本地联调时最常见的坑。服务端需要正确设置 CORS，并且前端 httpBatchLink 的 url 必须与 CORS origin 匹配。如果使用 Vite 开发服务器，可以配置代理把 /trpc 转发到后端，避免浏览器直接跨域。生产部署时建议将前后端放在同一域名下，通过 Nginx 或 CDN 反向代理。
错误处理还可以通过服务端的 errorFormatter 统一格式化，避免把数据库异常、堆栈信息暴露给客户端。虽然 tRPC 默认会返回错误码和简短信息，但在生产环境应该只输出与业务相关的提示，同时把完整错误记录到服务端日志系统。