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

第4章 Fetch / Edge Runtimes 适配器

版本:10.x Fetch / Edge Runtimes Adapter 你可以在任何遵循 WinterCG(具体是 Minimum Common Web Platform API 规范)的 edge runtime 中创建 tRPC 服务器。 这类 runtime 包括但不限于: Cloudflare Workers Deno Deploy Vercel Edge Runtime(以及 Next.js Edge Runtime) 这也让 tRPC 可以轻松集成到使用 Web 平台 API 表示请求和响应的框架中,例如: Astro(SSR 模式) Remix SolidStart 示例应用​ 描述链接 Cloudflare Workers 示例 Source Deno Deploy 示例 Source Next.js Edge Runtime 示例 Source Vercel Edge Runtime 示例 Source 如何在 edge runtime 中使用 tRPC 服务器​ tRPC 提供了一个 fetch adapter,以原生的 Request 和 Response API 作为输入和输出。tRPC 相关的代码在所有 runtime 中完全一致,唯一的区别在于响应的返回方式。 tRPC 开箱即用,内置了对原生 Fetch API 的 adapter。它可以把你的 tRPC router 转换成一个返回 Response 对象的 Request 处理器。 所需的 Web API​ tRPC 服务器依赖以下 Fetch API: Request、Response fetch Headers URL 只要你的 runtime 支持这些 API,就可以运行 tRPC 服务器。 提示 有趣的是:这也意味着你可以在浏览器里运行 tRPC 服务器! 通用设置​ 安装依赖​ 提示 如果你使用 Deno Deploy,可以跳过这一步。 npmyarnpnpmbunshnpm install @trpc/server zod shnpm install @trpc/server zodshyarn add @trpc/server zod shyarn add @trpc/server zodshpnpm add @trpc/server zod shpnpm add @trpc/server zodshbun add @trpc/server zod shbun add @trpc/server zod Zod 并非必需依赖,但下面的示例 router 会用到它。 创建 router​ 首先需要一个 router 来处理你的 query、mutation 和 subscription。 下面是一个示例 router,把它保存为 router.ts。 router.tsrouter.tstsimport { initTRPC } from '@trpc/server';import { z } from 'zod';import { Context } from './context';type User = { id: string; name: string; bio?: string;};const users: Record = {};export const t = initTRPC.context().create();export const appRouter = t.router({ getUserById: t.procedure.input(z.string()).query((opts) => { return users[opts.input]; // input type is string }), createUser: t.procedure // validate input with Zod .input( z.object({ name: z.string().min(3), bio: z.string().max(142).optional(), }), ) .mutation((opts) => { const id = Date.now().toString(); const user: User = { id, ...opts.input }; users[user.id] = user; return user; }),});// export type definition of APIexport type AppRouter = typeof appRouter; router.tstsimport { initTRPC } from '@trpc/server';import { z } from 'zod';import { Context } from './context';type User = { id: string; name: string; bio?: string;};const users: Record = {};export const t = initTRPC.context().create();export const appRouter = t.router({ getUserById: t.procedure.input(z.string()).query((opts) => { return users[opts.input]; // input type is string }), createUser: t.procedure // validate input with Zod .input( z.object({ name: z.string().min(3), bio: z.string().max(142).optional(), }), ) .mutation((opts) => { const id = Date.now().toString(); const user: User = { id, ...opts.input }; users[user.id] = user; return user; }),});// export type definition of APIexport type AppRouter = typeof appRouter; 如果 router 文件变得过大,可以把它拆分成多个子 router,分别放在各自的文件里,再合并成一个根 appRouter。 创建 context​ 接下来需要创建一个 context,它会在每次请求时被创建。 下面是一个示例 context,把它保存为 context.ts: context.tscontext.tstsimport { FetchCreateContextFnOptions } from '@trpc/server/adapters/fetch';export function createContext({ req, resHeaders,}: FetchCreateContextFnOptions) { const user = { name: req.headers.get('username') ?? 'anonymous' }; return { req, resHeaders, user };}export type Context = Awaited>; context.tstsimport { FetchCreateContextFnOptions } from '@trpc/server/adapters/fetch';export function createContext({ req, resHeaders,}: FetchCreateContextFnOptions) { const user = { name: req.headers.get('username') ?? 'anonymous' }; return { req, resHeaders, user };}export type Context = Awaited>; 各 runtime 的具体设置​ Astro​ src/pages/trpc/[trpc].tstsimport { fetchRequestHandler } from '@trpc/server/adapters/fetch';import type { APIRoute } from 'astro';import { createContext } from '../../server/context';import { appRouter } from '../../server/router';export const all: APIRoute = (opts) => { return fetchRequestHandler({ endpoint: '/trpc', req: opts.request, router: appRouter, createContext, });}; src/pages/trpc/[trpc].tstsimport { fetchRequestHandler } from '@trpc/server/adapters/fetch';import type { APIRoute } from 'astro';import { createContext } from '../../server/context';import { appRouter } from '../../server/router';export const all: APIRoute = (opts) => { return fetchRequestHandler({ endpoint: '/trpc', req: opts.request, router: appRouter, createContext, });}; Cloudflare Worker​ 注意 运行 Cloudflare Workers 需要 Wrangler CLI。 创建 Cloudflare Worker​ server.tstsimport { fetchRequestHandler } from '@trpc/server/adapters/fetch';import { createContext } from './context';import { appRouter } from './router';export default { async fetch(request: Request): Promise { return fetchRequestHandler({ endpoint: '/trpc', req: request, router: appRouter, createContext, }); },}; server.tstsimport { fetchRequestHandler } from '@trpc/server/adapters/fetch';import { createContext } from './context';import { appRouter } from './router';export default { async fetch(request: Request): Promise { return fetchRequestHandler({ endpoint: '/trpc', req: request, router: appRouter, createContext, }); },}; 运行 wrangler dev server.ts,你的端点就可以通过 HTTP 访问了! 端点HTTP URIgetUserGET http://localhost:8787/trpc/getUserById?input=INPUT

其中,INPUT 是 URI 编码的 JSON 字符串。
createUser POST http://localhost:8787/trpc/createUser

type User 的 req.body Deno Oak 注:此部分假定你已安装并配置好 Deno。更多信息请参考其入门指南。 更新 router.ts 中的导入 ```typescript import { initTRPC } from 'npm:@trpc/server'; import { z } from 'npm:zod'; import { Context } from './context.ts'; ``` 更新 context.ts 中的导入 ```typescript import { FetchCreateContextFnOptions } from 'npm:@trpc/server/adapters/fetch'; ``` 在 app.ts 中使用 fetchRequestHandler 配合 Oak ```typescript import { Application, Router } from 'https://deno.land/x/oak/mod.ts'; import { fetchRequestHandler } from 'npm:@trpc/server/adapters/fetch'; import { createContext } from './context.ts'; import { appRouter } from './router.ts'; const app = new Application(); const router = new Router(); router.all('/trpc/(.*)', async (ctx) => { const res = await fetchRequestHandler({ endpoint: '/trpc', req: new Request(ctx.request.url, { headers: ctx.request.headers, body: ctx.request.method !== 'GET' && ctx.request.method !== 'HEAD' ? ctx.request.body({ type: 'stream' }).value : void 0, method: ctx.request.method, }), router: appRouter, createContext, }); ctx.response.status = res.status; ctx.response.headers = res.headers; ctx.response.body = res.body; }); app.use(router.routes()); app.use(router.allowedMethods()); await app.listen({ port: 3000 }); ``` Deno Deploy 注:此部分假定你已安装并配置好 Deno。更多信息请参考其入门指南。 提示:可参考我们的 Deno Deploy 示例应用,查看实际运行案例。 更新 router.ts 中的导入 ```typescript import { initTRPC } from 'npm:@trpc/server'; import { z } from 'npm:zod'; import { Context } from './context.ts'; ``` 更新 context.ts 中的导入 ```typescript import { FetchCreateContextFnOptions } from 'npm:@trpc/server/adapters/fetch'; ``` 创建 Deno Deploy Function ```typescript import { fetchRequestHandler } from 'npm:@trpc/server/adapters/fetch'; import { createContext } from './context.ts'; import { appRouter } from './router.ts'; function handler(request) { return fetchRequestHandler({ endpoint: '/trpc', req: request, router: appRouter, createContext, }); } Deno.serve(handler); ``` 运行 `deno run --allow-net=:8000 --allow-env ./server.ts`,你的端点即可通过 HTTP 访问! 端点 | HTTP URI ---|--- getUser | GET http://localhost:8000/trpc/getUserById?input=INPUT

其中 INPUT 是经过 URI 编码的 JSON 字符串。createUserPOST http://localhost:8000/trpc/createUser

req.body 类型为 User Next.js Edge Runtime​ 完整示例点此。 Remix​ app/routes/trpc/$trpc.tstsimport type { ActionArgs, LoaderArgs } from '@remix-run/node';import { fetchRequestHandler } from '@trpc/server/adapters/fetch';import { createContext } from '~/server/context';import { appRouter } from '~/server/router';export const loader = async (args: LoaderArgs) => { return handleRequest(args);};export const action = async (args: ActionArgs) => { return handleRequest(args);};function handleRequest(args: LoaderArgs | ActionArgs) { return fetchRequestHandler({ endpoint: '/trpc', req: args.request, router: appRouter, createContext, });} app/routes/trpc/$trpc.tstsimport type { ActionArgs, LoaderArgs } from '@remix-run/node';import { fetchRequestHandler } from '@trpc/server/adapters/fetch';import { createContext } from '~/server/context';import { appRouter } from '~/server/router';export const loader = async (args: LoaderArgs) => { return handleRequest(args);};export const action = async (args: ActionArgs) => { return handleRequest(args);};function handleRequest(args: LoaderArgs | ActionArgs) { return fetchRequestHandler({ endpoint: '/trpc', req: args.request, router: appRouter, createContext, });} SolidStart​ src/routes/api/trpc/[trpc].tstsimport { fetchRequestHandler } from '@trpc/server/adapters/fetch';import type { APIEvent } from 'solid-start';import { createContext } from '../../server/context';import { appRouter } from '../../server/router';const handler = (event: APIEvent) => fetchRequestHandler({ endpoint: '/api/trpc', req: event.request, router: appRouter, createContext, });export { handler as GET, handler as POST }; src/routes/api/trpc/[trpc].tstsimport { fetchRequestHandler } from '@trpc/server/adapters/fetch';import type { APIEvent } from 'solid-start';import { createContext } from '../../server/context';import { appRouter } from '../../server/router';const handler = (event: APIEvent) => fetchRequestHandler({ endpoint: '/api/trpc', req: event.request, router: appRouter, createContext, });export { handler as GET, handler as POST }; Vercel Edge Runtime​ note参考官方 Vercel Edge Runtime 文档获取更多详情。 tip查看我们的 Vercel Edge Runtime 示例应用。 安装依赖​ npmyarnpnpmbunshnpm install -g edge-runtime shnpm install -g edge-runtimeshyarn global add edge-runtime shyarn global add edge-runtimeshpnpm add -g edge-runtime shpnpm add -g edge-runtimeshbun add -g edge-runtime shbun add -g edge-runtime 创建 Edge Runtime Function​ server.tstsimport { fetchRequestHandler } from '@trpc/server/adapters/fetch';import { createContext } from './context';import { appRouter } from './router';addEventListener('fetch', (event) => { return event.respondWith( fetchRequestHandler({ endpoint: '/trpc', req: event.request, router: appRouter, createContext, }), );}); server.tstsimport { fetchRequestHandler } from '@trpc/server/adapters/fetch';import { createContext } from './context';import { appRouter } from './router';addEventListener('fetch', (event) => { return event.respondWith( fetchRequestHandler({ endpoint: '/trpc', req: event.request, router: appRouter, createContext, }), );}); 执行 edge-runtime --listen server.ts --port 3000,你的端点即可通过 HTTP 访问! EndpointHTTP URIgetUserGET http://localhost:3000/trpc/getUserById?input=INPUT

其中 INPUT 为经 URI 编码的 JSON 字符串。向 http://localhost:3000/trpc/createUser 发送 createUser POST 请求

其请求体 req.body 的类型为 User

评论 (0)