进阶 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 字符串。
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
此处 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