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

第10章 tRPC 在 Edge Runtime 中的 Fetch 适配器指南

版本:11.x Fetch / Edge Runtimes 适配器 你可以在任何遵循 WinterCG(特别是 Minimum Common Web Platform API 规范)的 Edge Runtime 中创建 tRPC 服务器。 这些运行时包括(但不限于): Cloudflare Workers Deno Deploy Vercel Edge Runtime(以及 Next.js Edge Runtime) 这也使其能够轻松集成到使用 Web 平台 API 来表示请求和响应的框架中,例如: Astro(SSR 模式) Remix SolidStart 示例应用​ 描述 链接 Cloudflare Workers 示例 源码 Deno Deploy 示例 源码 Next.js Edge Runtime 示例 源码 Vercel Edge Runtime 示例 源码 如何在 Edge Runtime 中使用 tRPC 服务器​ tRPC 提供了一个 Fetch 适配器,它使用原生的 Request 和 Response API 作为输入和输出。tRPC 的核心代码在所有运行时中都是一样的,唯一的区别在于响应返回的方式。 tRPC 开箱即用地包含了针对原生 Fetch API 的适配器。该适配器允许你将 tRPC 路由转换为返回 Response 对象的请求处理器。 所需的 Web API​ tRPC 服务器使用以下 Fetch API: Request、Response fetch Headers URL 如果你的运行时支持这些 API,就可以使用 tRPC 服务器。 小贴士 冷知识:这意味着你也可以在浏览器中运行 tRPC 服务器! 通用配置​ 安装依赖​ 小贴士 如果使用 Deno Deploy,可以跳过此步骤。 npmyarnpnpmbundenonpm install @trpc/server @trpc/client zodyarn add @trpc/server @trpc/client zodpnpm add @trpc/server @trpc/client zodbun add @trpc/server @trpc/client zoddeno add npm:@trpc/server npm:@trpc/client npm:zod Zod 不是必需的依赖项,但在下面的示例路由中会用到。 AI 代理 如果你使用 AI 编程代理,请安装 tRPC 技能以获得更好的代码生成效果: bash npx @tanstack/intent@latest install 创建路由​ 首先,你需要一个路由来处理查询、变更和订阅。 下面提供了一个示例路由,请将其保存在名为 router.ts 的文件中。 router.ts import { initTRPC } from '@trpc/server'; import { z } from 'zod'; import type { 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]; // 输入类型为字符串 }), createUser: t.procedure // 使用 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; }), }); // 导出 API 的类型定义 export type AppRouter = typeof appRouter; 如果路由文件变得太大,可以将路由拆分为多个子路由,每个子路由在单独的文件的实现。然后将它们合并到一个根 appRouter 中。 创建上下文​ 接下来,你需要为每个请求创建一个上下文。 下面提供了一个示例上下文,请将其保存在名为 context.ts 的文件中: context.ts import type { 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>; 运行时特定配置​ Astro​ src/pages/trpc/[trpc].ts import { 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​ 注意 你需要 Wrangler CLI 来运行 Cloudflare Workers。 创建 Cloudflare Worker​ server.ts import { 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 URI getUser GET http://localhost:8787/trpc/getUserById?input=INPUT

此处 INPUT 为经过 URI 编码的 JSON 字符串。在终端执行 createUser:POST http://localhost:8787/trpc/createUser

其中 req.body 的类型为 User Deno Oak​ 注意:前提是你已经安装并配置好 Deno,详情请参考其入门指南。 更新 router.ts 中的 import​ router.tstsimport { initTRPC } from 'npm:@trpc/server';import { z } from 'npm:zod';import { Context } from './context.ts'; 更新 context.ts 中的 import​ context.tstsimport { FetchCreateContextFnOptions } from 'npm:@trpc/server/adapters/fetch'; 在 app.ts 中将 fetchRequestHandler 与 Oak 结合使用​ app.tstsimport { 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 中的 import​ router.tstsimport { initTRPC } from 'npm:@trpc/server';import { z } from 'npm:zod';import { Context } from './context.ts'; 更新 context.ts 中的 import​ context.tstsimport { FetchCreateContextFnOptions } from 'npm:@trpc/server/adapters/fetch'; 创建 Deno Deploy 函数​ server.tstsimport { 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,你的 endpoints 就可以通过 HTTP 访问了! EndpointHTTP URIgetUserGET http://localhost:8000/trpc/getUserById?input=INPUT

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

with req.body 的类型为 User Next.js Edge Runtime 完整示例参见此处。 Remix app/routes/trpc.$trpc.ts import type { ActionFunctionArgs, LoaderFunctionArgs } 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: LoaderFunctionArgs) => { return handleRequest(args); }; export const action = async (args: ActionFunctionArgs) => { return handleRequest(args); }; function handleRequest(args: LoaderFunctionArgs | ActionFunctionArgs) { return fetchRequestHandler({ endpoint: '/trpc', req: args.request, router: appRouter, createContext, }); } SolidStart src/routes/api/trpc/[trpc].ts import { fetchRequestHandler } from '@trpc/server/adapters/fetch'; import type { APIEvent } from '@solidjs/start/server'; 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 示例应用,查看实际用法。 安装依赖 npm yarn pnpm bun npm install -g edge-runtime yarn global add edge-runtime pnpm add -g edge-runtime bun add -g edge-runtime 创建 Edge Runtime 函数 server.ts import { fetchRequestHandler } from '@trpc/server/adapters/fetch'; import { createContext } from './context'; import { appRouter } from './router'; // Vercel Edge Runtime 采用 Service Worker 风格的 addEventListener addEventListener('fetch', (event: any) => { return event.respondWith( fetchRequestHandler({ endpoint: '/trpc', req: event.request, router: appRouter, createContext, }), ); }); 运行 edge-runtime --listen server.ts --port 3000 后,相关端点即可通过 HTTP 访问! Endpoint HTTP URI getUser GET http://localhost:3000/trpc/getUserById?input=INPUT

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

请求体 req.body 的类型为 User

评论 (0)