tRPC最大的卖点就是端到端类型安全：服务端定义一次Router，前端通过createTRPCProxyClient或React Query集成直接拿到精确的输入输出类型，理论上不存在类型漂移。但真实项目里，很多团队还是会遇到客户端类型不匹配的问题——明明本地开发一切正常，CI构建却报类型错误；或者第三方接入方拿着过期的类型定义调接口，运行时直接抛错。这篇文章就来拆解这个问题的根源，并给出一套基于OpenAPI生成与版本锁定的可落地方案。
tRPC类型不匹配到底是怎么产生的
首先要明确一点：tRPC的类型安全是编译期契约，它依赖于客户端直接import服务端的AppRouter类型。这个机制在纯Web同仓场景下非常可靠，因为前后端共享同一份TypeScript源码，类型检查在构建时就能发现问题。
但一旦出现以下情况，这条类型链路就会断开。第一种是异构客户端：移动端用Kotlin或Swift开发，根本无法消费TypeScript类型，只能靠手写接口文档或口口相传的字段约定。第二种是monorepo依赖漂移：客户端和服务端分别是两个package，各自锁定了不同版本的共享schema包，服务端加了字段、客户端还在用旧类型，编译期看似安全，运行时却可能出现字段缺失。第三种是构建顺序问题：客户端构建时引用的types包是上一次构建的产物，CI缓存没有失效，导致类型定义滞后于实际服务端代码。
还有一类问题更具迷惑性：代码本身没变，但TypeScript版本升级或strict配置调整后，原本能通过的类型推导突然报错。tRPC大量依赖泛型推导和条件类型，对TS版本相当敏感，这也是排查类型不匹配时容易忽略的一点。
用OpenAPI规范桥接tRPC与异构客户端
既然移动端和第三方系统消费不了TypeScript类型，就需要一个中立的接口描述格式，OpenAPI是目前事实上的标准。社区里有成熟的trpc-openapi方案，它允许你在定义procedure时追加OpenAPI元数据，然后从tRPC Router直接生成OpenAPI文档。
import { initTRPC } from '@trpc/server';
import { z } from 'zod';
const t = initTRPC.meta<OpenApiMeta>().context<Context>().create();
export const appRouter = t.router({
getUser: t.procedure
.meta({ openapi: { method: 'GET', path: '/users/{id}' } })
.input(z.object({ id: z.string() }))
.output(z.object({ id: z.string(), name: z.string() }))
.query(async ({ input }) => {
return await getUserById(input.id);
}),
});生成文档之后，就可以用openapi-typescript、openapi-generator等工具为各类客户端生成强类型代码。生成的类型定义和服务端schema之间形成单一事实来源：只要文档是从Router生成的，而不是手写的，客户端类型就不会和服务端实现脱节。这里有个实践建议：不要把生成文档这一步留给开发者手动执行，应该放进CI流水线，每次合并代码自动重新生成并提交，避免文档滞后。
需要注意的是，trpc-openapi对procedure有一定约束，比如input必须是可以映射到路径参数和查询参数的对象，复杂的嵌套结构更适合走POST body。在设计接口时就要考虑这一点，不要事后再补救，否则会陷入为了兼容生成器而扭曲业务模型的尴尬局面。
monorepo下的版本锁定策略
解决了异构客户端，回头处理monorepo内部的类型漂移。核心思路是让schema包成为独立发布的版本化产物，而不是让客户端直接引用服务端源码。
具体做法是：把zod schema、Router类型、以及生成的OpenAPI文档抽取到一个独立的@app/contract包中，服务端和所有客户端都依赖这个包。在pnpm workspace下，务必确认workspace协议版本和实际发布版本一致，避免本地用link、线上用registry版本导致的行为差异。发布时采用锁步发布：contract包的版本号与服务端API版本关联，服务端任何破坏性变更都必须先升级contract的major版本。
{
"name": "@app/web-client",
"dependencies": {
"@app/contract": "2.4.1"
}
}同时要在CI中加一道类型守门检查：在客户端构建阶段，先重新生成一次OpenAPI文档，与contract包中提交的文档做diff，如果不一致就直接失败，提示开发者忘记更新契约。这个检查成本很低，但能挡住绝大多数静默漂移。类似的，可以用attw或tsc的--noEmit模式对contract包做类型兼容性验证，确保下游升级时不会出现意外的类型断裂。
渐进式迁移与日常防漂移实践
存量项目不可能一夜之间全部改造，建议按接口分批推进。先从类型问题最高发的模块开始，比如字段频繁变动的列表接口，给它补上OpenAPI meta并生成类型，其他接口继续走原生tRPC类型。两者并不冲突，trpc-openapi的meta是可选的，没标注的procedure照常工作。
日常开发中有几条经验值得坚持。第一，schema变更必须走PR评审，契约包的diff要在PR里明确展示，让reviewer一眼看出破坏性变更。第二，客户端升级契约包时使用精确版本号，禁止^和~这类浮动范围，浮动版本是类型漂移的温床。第三，统一团队内TypeScript版本，把它也放进contract包的peerDependencies里，避免不同子项目用不同TS版本推导出不同结果。
最后要建立一个观念：类型安全不是工具自动送你的礼物，而是一套需要持续维护的工程约定。tRPC负责编译期推导，OpenAPI负责跨语言契约，版本锁定负责发布秩序，三者结合起来，客户端类型不匹配的问题才能被真正关进笼子里，而不是靠每次出问题时手动对一遍字段来救火。