进阶 trpc.io 2026-10-12 05:42:24 · 27 阅读

第6章 tRPC 独立适配器详解

Version: 10.xStandalone Adapter(独立适配器)

tRPC 的 Standalone Adapter 是让新项目最快跑起来的方式,非常适合本地开发以及基于服务器的生产环境。它本质上就是对标准 Node.js HTTP Server 的一层封装,保留了常用的 tRPC 相关配置项。

如果你已有 Express、Fastify 或 Next.js 等现有 API 部署,想把 tRPC 集成进去,请查看各自的适配器文档。同样,如果你倾向于部署在 serverless 或边缘计算环境,也有 AWS Lambda、Fetch 等适配器可供选择。

还有一种很常见的做法:当生产环境的适配器在本地难以运行时,可以让应用保留两个入口——本地开发用 Standalone Adapter,部署时换用其他适配器。

示例应用 描述链接 Standalone tRPC ServerStackBlitz源码 带 CORS 处理的 Standalone tRPC ServerStackBlitz源码

搭建 Standalone tRPC Server

1. 实现 App Router

先实现你的 tRPC router,例如:

appRouter.tstsimport { initTRPC } from '@trpc/server';import { z } from 'zod';export const t = initTRPC.create();export const appRouter = t.router({ getUser: t.procedure.input(z.string()).query((opts) => { return { id: opts.input, name: 'Bilbo' }; }), createUser: t.procedure .input(z.object({ name: z.string().min(5) })) .mutation(async (opts) => { // use your ORM of choice return await UserModel.create({ data: opts.input, }); }),});// export type definition of APIexport type AppRouter = typeof appRouter;

更多信息请参考 quickstart 指南。

2. 使用 Standalone adapter

Standalone adapter 会启动一个简单的 Node.js HTTP 服务器。

server.tstsimport { initTRPC } from '@trpc/server';import { createHTTPServer } from '@trpc/server/adapters/standalone';import { appRouter } from './appRouter.ts';createHTTPServer({ router: appRouter, createContext() { console.log('context 3'); return {}; },}).listen(2022);

处理 CORS 与 OPTIONS 请求

默认情况下,standalone 服务器不会响应 HTTP OPTIONS 请求,也不会设置任何 CORS 头。

如果你的部署环境(比如本地开发)无法替你处理这些问题,就需要自己处理。

1. 安装 cors

可以借助流行的 cors 包自行添加支持:

bashyarn add corsyarn add -D @types/cors

关于该包的完整配置方式,请查阅其文档。

2. 配置 Standalone 服务器

下面的示例对任意请求都放开了 CORS,这在开发环境很方便,但在生产环境中应该配置得更严格。

server.tstsimport { initTRPC } from '@trpc/server';import { createHTTPServer } from '@trpc/server/adapters/standalone';import cors from 'cors';createHTTPServer({ middleware: cors(), router: appRouter, createContext() { console.log('context 3'); return {}; },}).listen(3333);

middleware 选项接受任何形似 connect/Node.js 中间件的函数,因此用途不只是处理 CORS。不过它的定位只是一个简单的"逃生舱口",本身不支持组合多个中间件。如果你有这个需求,可以选择:

- 换用中间件支持更完善的适配器,比如 Express adapter - 使用 connect 之类的方案来组合中间件 - 基于自定义 http server 扩展 Standalone 的 createHTTPHandler(见下文)

更进一步

如果 createHTTPServer 无法满足需求,还可以用 standalone adapter 的 createHTTPHandler 函数配合自己的 HTTP Server。例如:

server.tstsimport { createServer } from 'http';import { initTRPC } from '@trpc/server';import { createHTTPHandler } from '@trpc/server/adapters/standalone';const handler = createHTTPHandler({ router: appRouter, createContext() { return {}; },});createServer((req, res) => { / * Handle the request however you like, * just call the tRPC handler when you're ready */ handler(req, res);}).listen(3333);

评论 (0)