版本：11.x

在 Next.js Pages Router 中的设置

非官方测试版翻译

本页面由 PageTurner AI 翻译（测试版）。未经项目官方认可。发现错误？报告问题 →

注意

本指南适用于 Next.js Pages Router。若您使用带有 React Server Components 的 Next.js App Router，请查阅 RSC 文档

在现有 Next.js 项目中集成 tRPC

1. 安装依赖

npm
yarn
pnpm
bun
deno

npm install @trpc/server @trpc/client @trpc/react-query @trpc/next @tanstack/react-query@latest zod

yarn add @trpc/server @trpc/client @trpc/react-query @trpc/next @tanstack/react-query@latest zod

pnpm add @trpc/server @trpc/client @trpc/react-query @trpc/next @tanstack/react-query@latest zod

bun add @trpc/server @trpc/client @trpc/react-query @trpc/next @tanstack/react-query@latest zod

deno add npm:@trpc/server npm:@trpc/client npm:@trpc/react-query npm:@trpc/next npm:@tanstack/react-query@latest npm:zod

Next.js 集成实际上是我们的 React Query 集成与 Next.js 特定功能的结合。

2. 启用严格模式

若使用 Zod 进行输入验证，需在 tsconfig.json 中启用严格模式：

tsconfig.json
diff
"compilerOptions": {
+   "strict": true
}

tsconfig.json
diff
"compilerOptions": {
+   "strict": true
}

如果严格模式限制过强，你至少需要启用 strictNullChecks：

tsconfig.json
diff
"compilerOptions": {
+   "strictNullChecks": true
}

tsconfig.json
diff
"compilerOptions": {
+   "strictNullChecks": true
}

3. 创建 tRPC 路由

在 src/server/trpc.ts 中使用 initTRPC 函数初始化 tRPC 后端，并创建你的第一个路由器。我们将在此创建一个简单的 "hello world" 路由器和过程 - 关于创建 tRPC API 的深入信息，请参考：

了解 tRPC 的快速入门指南和后端使用文档
关于在 Next.js 服务器中挂载 tRPC 的 Next.js 适配器文档

View sample backend

server/trpc.ts
ts
import { initTRPC } from '@trpc/server';
// Avoid exporting the entire t-object
// since it's not very descriptive.
// For instance, the use of a t variable
// is common in i18n libraries.
const t = initTRPC.create();
// Base router and procedure helpers
export const router = t.router;
export const procedure = t.procedure;

server/trpc.ts
ts
import { initTRPC } from '@trpc/server';
// Avoid exporting the entire t-object
// since it's not very descriptive.
// For instance, the use of a t variable
// is common in i18n libraries.
const t = initTRPC.create();
// Base router and procedure helpers
export const router = t.router;
export const procedure = t.procedure;

server/routers/_app.ts
ts
import { z } from 'zod';
import { procedure, router } from '../trpc';
export const appRouter = router({
  hello: procedure
    .input(
      z.object({
        text: z.string(),
      }),
    )
    .query((opts) => {
      return {
        greeting: `hello ${opts.input.text}`,
      };
    }),
});
// export type definition of API
export type AppRouter = typeof appRouter;

server/routers/_app.ts
ts
import { z } from 'zod';
import { procedure, router } from '../trpc';
export const appRouter = router({
  hello: procedure
    .input(
      z.object({
        text: z.string(),
      }),
    )
    .query((opts) => {
      return {
        greeting: `hello ${opts.input.text}`,
      };
    }),
});
// export type definition of API
export type AppRouter = typeof appRouter;

pages/api/trpc/[trpc].ts
ts
import * as trpcNext from '@trpc/server/adapters/next';
import { appRouter } from '../../../server/routers/_app';
// export API handler
// @link https://trpc.io/docs/v11/server/adapters
export default trpcNext.createNextApiHandler({
  router: appRouter,
  createContext: () => ({}),
});

pages/api/trpc/[trpc].ts
ts
import * as trpcNext from '@trpc/server/adapters/next';
import { appRouter } from '../../../server/routers/_app';
// export API handler
// @link https://trpc.io/docs/v11/server/adapters
export default trpcNext.createNextApiHandler({
  router: appRouter,
  createContext: () => ({}),
});

备注

上述后端使用了推荐的文件结构，但你也可以简化处理，将所有内容直接放入 API 处理程序。

4. 创建 tRPC 钩子

使用 createTRPCNext 函数基于你的 API 类型签名创建一组强类型钩子。

utils/trpc.ts
tsx
import { httpBatchLink } from '@trpc/client';
import { createTRPCNext } from '@trpc/next';
import type { AppRouter } from '../server/routers/_app';
function getBaseUrl() {
  if (typeof window !== 'undefined')
    // browser should use relative path
    return '';
  if (process.env.VERCEL_URL)
    // reference for vercel.com
    return `https://${process.env.VERCEL_URL}`;
  if (process.env.RENDER_INTERNAL_HOSTNAME)
    // reference for render.com
    return `http://${process.env.RENDER_INTERNAL_HOSTNAME}:${process.env.PORT}`;
  // assume localhost
  return `http://localhost:${process.env.PORT ?? 3000}`;
}
export const trpc = createTRPCNext<AppRouter>({
  config(config) {
    return {
      links: [
        httpBatchLink({
          /**
           * If you want to use SSR, you need to use the server's full URL
           * @see https://trpc.io/docs/v11/ssr
           **/
          url: `${getBaseUrl()}/api/trpc`,
          // You can pass any HTTP headers you wish here
          async headers() {
            return {
              // authorization: getAuthCookie(),
            };
          },
        }),
      ],
    };
  },
  /**
   * @see https://trpc.io/docs/v11/ssr
   **/
  ssr: false,
});

utils/trpc.ts
tsx
import { httpBatchLink } from '@trpc/client';
import { createTRPCNext } from '@trpc/next';
import type { AppRouter } from '../server/routers/_app';
function getBaseUrl() {
  if (typeof window !== 'undefined')
    // browser should use relative path
    return '';
  if (process.env.VERCEL_URL)
    // reference for vercel.com
    return `https://${process.env.VERCEL_URL}`;
  if (process.env.RENDER_INTERNAL_HOSTNAME)
    // reference for render.com
    return `http://${process.env.RENDER_INTERNAL_HOSTNAME}:${process.env.PORT}`;
  // assume localhost
  return `http://localhost:${process.env.PORT ?? 3000}`;
}
export const trpc = createTRPCNext<AppRouter>({
  config(config) {
    return {
      links: [
        httpBatchLink({
          /**
           * If you want to use SSR, you need to use the server's full URL
           * @see https://trpc.io/docs/v11/ssr
           **/
          url: `${getBaseUrl()}/api/trpc`,
          // You can pass any HTTP headers you wish here
          async headers() {
            return {
              // authorization: getAuthCookie(),
            };
          },
        }),
      ],
    };
  },
  /**
   * @see https://trpc.io/docs/v11/ssr
   **/
  ssr: false,
});

备注

createTRPCNext 与 tRPC-v9 的互操作模式不兼容。若您正在通过互操作模式从 v9 迁移，请继续使用旧版初始化方式。

5. 配置 `_app.tsx`

将根应用页面包裹在 trpc.withTRPC 高阶组件中，类似如下：

pages/_app.tsx
tsx
import type { AppType } from 'next/app';
import { trpc } from '../utils/trpc';
const MyApp: AppType = ({ Component, pageProps }) => {
  return <Component {...pageProps} />;
};
export default trpc.withTRPC(MyApp);

pages/_app.tsx
tsx
import type { AppType } from 'next/app';
import { trpc } from '../utils/trpc';
const MyApp: AppType = ({ Component, pageProps }) => {
  return <Component {...pageProps} />;
};
export default trpc.withTRPC(MyApp);

6. 发起 API 请求

全部设置完成！

现在您可以使用刚创建的 React Hook 调用 API。更多细节请参阅 React Query 集成文档

pages/index.tsx
tsx
import { trpc } from '../utils/trpc';
export default function IndexPage() {
  const hello = trpc.hello.useQuery({ text: 'client' });
  if (!hello.data) {
    return <div>Loading...</div>;
  }
  return (
    <div>
      <p>{hello.data.greeting}</p>
    </div>
  );
}

pages/index.tsx
tsx
import { trpc } from '../utils/trpc';
export default function IndexPage() {
  const hello = trpc.hello.useQuery({ text: 'client' });
  if (!hello.data) {
    return <div>Loading...</div>;
  }
  return (
    <div>
      <p>{hello.data.greeting}</p>
    </div>
  );
}

`createTRPCNext()` 的选项

`config` 回调函数

config 参数为返回配置对象的函数，用于设置 tRPC 和 React Query 客户端。该函数接收包含 Next.js req 对象等信息的 ctx 参数，返回对象支持以下属性：

必需：
links：用于定制 tRPC 客户端与服务器间的数据流。了解更多
可选：
queryClientConfig：用于配置 tRPC React 钩子内部使用的 React Query QueryClient 对象：QueryClient 文档
queryClient：一个 React Query 的 QueryClient 实例
- 注意：queryClient 和 queryClientConfig 只能二选一提供
transformer: 应用于输出数据的转换器。了解更多关于数据转换器的信息
abortOnUnmount: 决定组件卸载时是否取消进行中的请求。默认为 false

`overrides`：(默认值：`undefined`)

配置 React Query 钩子的覆盖选项

`ssr`-布尔值（默认：`false`）

控制 tRPC 在服务端渲染页面时是否等待查询完成，默认值为 false。

`responseMeta`-回调函数

用于在服务端渲染时设置响应头与 HTTP 状态码。

示例

utils/trpc.ts
tsx
import { createTRPCNext } from '@trpc/next';
import type { AppRouter } from '../pages/api/trpc/[trpc]';
export const trpc = createTRPCNext<AppRouter>({
  config(config) {
    /* [...] */
  },
});

utils/trpc.ts
tsx
import { createTRPCNext } from '@trpc/next';
import type { AppRouter } from '../pages/api/trpc/[trpc]';
export const trpc = createTRPCNext<AppRouter>({
  config(config) {
    /* [...] */
  },
});

后续步骤

浏览文档其他部分了解更多内容，例如授权机制、中间件和错误处理

您还可以了解查询和变更的相关信息，特别是现在您正在使用 @trpc/react-query

推荐文件结构​

在现有 Next.js 项目中集成 tRPC​

1. 安装依赖​

2. 启用严格模式​

3. 创建 tRPC 路由​

4. 创建 tRPC 钩子​

5. 配置 _app.tsx​

6. 发起 API 请求​

createTRPCNext() 的选项​

config 回调函数​

overrides：(默认值：undefined)​

ssr-布尔值（默认：false）​

responseMeta-回调函数​

示例​

后续步骤​

推荐文件结构