tRPC全栈类型安全需手动配置tsconfig路径、插件和Router泛型三要素：baseUrl必须为"."，paths须覆盖"@/trpc/"和"@/server/"，安装typescript-trpc-plugin并启用，createTRPCReact()必须显式传入AppRouter类型，调试需复合配置前后端断点。
tRPC全栈类型安全在VSCode里不是自动生效的，必须手动配齐tsconfig路径、插件、Router泛型三要素，缺一不可。
tsconfig.json的baseUrl和paths必须严格按项目根目录配置
VSCode报红import { trpc } from '@/trpc/client'但tsc编译通过，基本就是baseUrl或paths没对上。常见错误包括：baseUrl设成"./src"、留空、或写成"src"；paths漏掉@/server/*导致服务端类型无法被客户端引用。
-
baseUrl只能是"."（项目根目录），不能带斜杠或子路径 -
paths至少要覆盖"@/trpc/*": ["src/trpc/*"]和"@/server/*": ["src/server/*"] - 改完必须执行
Ctrl+Shift+P → "TypeScript: Restart TS server"，否则VSCode缓存不刷新 - 确保VSCode打开的是项目根目录，而不是
src或packages子文件夹
必须安装并启用typescript-trpc-plugin
原生TS完全无法推导router.query()链式调用的返回类型，trpc.post.create.useMutation() hover看不到参数结构，根本原因就是缺少插件支持。官方@trpc/client包不自带类型补全能力。
React Router Code Review
下载
审查 React Router 代码，确保数据加载、变更、错误处理和导航模式符合规范，适用于 React Router v6.4+ 代码、加载器及其他特性。
- 运行
npm install --save-dev typescript-trpc-plugin - 在
tsconfig.json的compilerOptions.plugins里加[{"name":"typescript-trpc-plugin"}] - 该插件只作用于
.ts文件，.tsx中使用useQuery等hook时，需确认@trpc/react-query版本与插件兼容（v10.40+稳定） - 若补全卡顿，可在插件配置加
"maxDepth": 2限制递归深度
createTRPCReact()必须显式传入AppRouter类型
写const trpc = createTRPCReact()会导致所有useQuery/useMutation返回any，IDE失去所有输入提示和类型校验。这不是bug，是TypeScript泛型未指定的必然结果。
- 服务端必须统一导出
AppRouter：在src/server/routers/_app.ts里写export type { AppRouter } from '@/server/trpc' - 客户端初始化必须显式标注：用
const trpc = createTRPCReact<approuter>()</approuter>，不能靠类型推断 - 避免把
createTRPCReact()写在组件内部——每次渲染都新建实例会破坏类型上下文 - 别用
z.any()或z.unknown()定义input，它们会切断类型传播链
VSCode调试tRPC请求需要复合配置而非单点断点
tRPC请求横跨前端React组件、Next.js API路由、服务端Router三层，只在useQuery打一个断点看不到实际resolver执行过程。必须用VSCode 2026的compositeLaunch模式同步挂载前后端调试器。
- 在
.vscode/launch.json里配置compounds，组合pwa-node（后端API路由）和pwa-chrome（前端页面） - 后端断点打在
src/pages/api/trpc/[trpc].ts的createNextApiHandler入口，或src/server/routers/*.ts的procedure resolver里 - 前端断点打在
trpc.xxx.useQuery()调用处，配合“Variables”面板里的Shared Context分组查看跨端数据流转 - 注意
httpLink的url必须和createNextApiHandler监听地址一致，否则调试器收不到真实请求
最易被忽略的是AppRouter类型的导出位置和引用路径是否真正一致——哪怕多一个../或少一个index.ts，都会让整个端到端类型链断裂，且VSCode不会报错，只会静默退化为any。
