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

第12章 Standalone Adapter 指南

版本:11.x Standalone Adapter tRPC 的 Standalone Adapter 是启动新项目最简单的方式。它非常适合本地开发以及基于服务器的生产环境。本质上,它只是在标准的 Node.js HTTP Server 外层包了一个壳,保留了 tRPC 相关的常规配置选项。

如果你已经有像 Express、Fastify 或 Next.js 这样的现有 API 部署,并想在其中集成 tRPC,建议查看它们各自对应的 adapter。同样,如果你偏好将服务部署在 serverless 或 edge compute 环境,我们提供了如 AWS Lambda 和 Fetch 等 adapter,可能更符合你的需求。

另外,如果部署环境中使用的 adapter 难以在本地机器上运行,应用中同时维护两个入口点也很常见。你可以在本地开发时使用 Standalone Adapter,而在部署时切换到其他 adapter。

示例应用 描述 链接 Standalone tRPC Server StackBlitz Source 带 CORS 处理的 Standalone tRPC Server StackBlitz Source

AI Agents 如果你使用 AI 编码代理,可以安装 tRPC skills 以获得更好的代码生成效果: bash npx @tanstack/intent@latest install bash npx @tanstack/intent@latest install

搭建 Standalone tRPC 服务器 1. 实现 App Router 实现你的 tRPC router,例如: appRouter.ts import { 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 { id: '1', ...opts.input }; }), });

// export type definition of API export type AppRouter = typeof appRouter; appRouter.ts import { 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 { id: '1', ...opts.input }; }), });

// export type definition of API export type AppRouter = typeof appRouter; 如需更多信息,请参阅快速入门指南。

2. 使用 Standalone Adapter Standalone Adapter 会运行一个简单的 Node.js HTTP 服务器。 server.ts import { createHTTPServer } from '@trpc/server/adapters/standalone'; import { appRouter } from './appRouter';

createHTTPServer({ router: appRouter, createContext() { return {}; }, // basePath: '/trpc/', // optional, defaults to '/' }).listen(2022); server.ts import { createHTTPServer } from '@trpc/server/adapters/standalone'; import { appRouter } from './appRouter';

createHTTPServer({ router: appRouter, createContext() { return {}; }, // basePath: '/trpc/', // optional, defaults to '/' }).listen(2022);

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

如果你所处的环境无法自动处理这些(例如本地开发),你可能需要自行处理。

1. 安装 cors 你可以使用流行的 cors 包来添加支持: bash yarn add cors yarn add -D @types/cors bash yarn add cors yarn add -D @types/cors 有关该包的完整配置信息,请查阅官方文档。

2. 配置 Standalone 服务器 下面的示例将 CORS 对所有请求开放,这在开发阶段很有用,但在生产环境中,你应当且必须更严格地配置它。 server.ts import { createHTTPServer } from '@trpc/server/adapters/standalone'; import cors from 'cors'; import { appRouter } from './appRouter';

createHTTPServer({ middleware: cors(), router: appRouter, createContext() { return {}; }, }).listen(3333); server.ts import { createHTTPServer } from '@trpc/server/adapters/standalone'; import cors from 'cors'; import { appRouter } from './appRouter';

createHTTPServer({ middleware: cors(), router: appRouter, createContext() { return {}; }, }).listen(3333); middleware 选项接受任何类似 connect/node.js 中间件的函数,因此如果你愿意,它可以用于 CORS 处理之外的更多场景。不过,它的设计初衷是提供一个简单的逃生舱口(escape hatch),因此无法单独用于组合多个中间件。如果你希望实现这一功能,可以:

使用支持更全面中间件的替代 adapter,例如 Express adapter 使用如 connect 这样的方案来组合中间件 使用自定义 HTTP 服务器扩展 Standalone 的 createHTTPHandler(见下文)

为自定义 HTTP 服务器添加处理程序 createHTTPServer 返回的是 Node 内置 http.Server 的实例,这意味着你可以访问其所有属性和 API。然而,如果 createHTTPServer 无法满足你的使用场景,你也可以使用 Standalone adapter 的 createHTTPHandler 函数来创建自己的 HTTP 服务器。例如: server.ts import { createServer } from 'http'; import { createHTTPHandler } from '@trpc/server/adapters/standalone'; import { appRouter } from './appRouter';

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(3001); server.ts import { createServer } from 'http'; import { createHTTPHandler } from '@trpc/server/adapters/standalone'; import { appRouter } from './appRouter';

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(3001);

自定义请求处理的基础路径 Standalone adapter 还支持 basePath 选项,它会从请求路径的开头截去 basePath。 server.ts import { createServer } from 'http'; import { createHTTPHandler } from '@trpc/server/adapters/standalone'; import { appRouter } from './appRouter';

const handler = createHTTPHandler({ router: appRouter, basePath: '/trpc/', });

createServer((req, res) => { if (req.url?.startsWith('/trpc/')) { return handler(req, res); } // [... insert your custom logic here ...]

res.statusCode = 404; res.end('Not Found'); }).listen(3001); server.ts import { createServer } from 'http'; import { createHTTPHandler } from '@trpc/server/adapters/standalone'; import { appRouter } from './appRouter';

const handler = createHTTPHandler({ router: appRouter, basePath: '/trpc/', });

createServer((req, res) => { if (req.url?.startsWith('/trpc/')) { return handler(req, res); } // [... insert your custom logic here ...]

res.statusCode = 404; res.end('Not Found'); }).listen(3001);

HTTP/2 Standalone adapter 也支持 HTTP/2。 server.ts import http2 from 'http2'; import { createHTTP2Handler } from '@trpc/server/adapters/standalone'; import { appRouter } from './_app'; import { createContext } from './context';

const handler = createHTTP2Handler({ router: appRouter, createContext, // basePath: '/trpc/', // optional, defaults to '/' });

const server = http2.createSecureServer( { key: '...', cert: '...', }, (req, res) => { / * Handle the request however you like, * just call the tRPC handler when you're ready */ handler(req, res); }, );

server.listen(3001); server.ts import http2 from 'http2'; import { createHTTP2Handler } from '@trpc/server/adapters/standalone'; import { appRouter } from './_app'; import { createContext } from './context';

const handler = createHTTP2Handler({ router: appRouter, createContext, // basePath: '/trpc/', // optional, defaults to '/' });

const server = http2.createSecureServer( { key: '...', cert: '...', }, (req, res) => { / * Handle the request however you like, * just call the tRPC handler when you're ready */ handler(req, res); }, );

server.listen(3001); context.ts import { CreateHTTP2ContextOptions } from '@trpc/server/adapters/standalone';

export async function createContext(opts: CreateHTTP2ContextOptions) { opts.req; (property) req: http2.Http2ServerRequest opts.res; (property) res: http2.Http2ServerResponse

opts.info; (property) info: TRPCRequestInfo return {}; }

export type Context = Awaited>; context.ts import { CreateHTTP2ContextOptions } from '@trpc/server/adapters/standalone';

export async function createContext(opts: CreateHTTP2ContextOptions) { opts.req; (property) req: http2.Http2ServerRequest opts.res; (property) res: http2.Http2ServerResponse

opts.info; (property) info: TRPCRequestInfo return {}; }

export type Context = Awaited>;

评论 (0)