进阶 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
其中,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