能否将基于Next.js Page Router的T3 Stack项目迁移至App Router？

可行性说明 #

完全可行。Next.js 13.4+的App Router已进入稳定阶段，T3 Stack核心技术（TypeScript、Tailwind、tRPC）均能完美适配App Router的服务器组件、路由组、并行路由等新特性，无需担心兼容性问题。

迁移步骤 #

1. 环境前置检查 #

• 保持Next.js版本在13.4.19或升级至最新稳定版（推荐升级，规避已知小版本兼容性bug）
• 确认tRPC、@trpc/next等依赖为v10+版本，该版本原生支持App Router

2. 目录结构重构 #

• 在项目根目录新建app文件夹，作为App Router核心目录
• 逐步迁移pages下的页面文件：
  • 原pages/index.tsx → app/page.tsx
  • 原动态路由pages/post/[id].tsx → app/post/[id]/page.tsx
  • 用括号包裹目录创建路由组，如app/(auth)/login/page.tsx，不会影响最终URL路径

3. Tailwind CSS适配 #

• 仅需更新tailwind.config.js的content配置，加入app目录即可：

  /** @type {import('tailwindcss').Config} */
  module.exports = {
    content: [
      "./app/**/*.{js,ts,jsx,tsx,mdx}",
      "./pages/**/*.{js,ts,jsx,tsx,mdx}",
      "./components/**/*.{js,ts,jsx,tsx,mdx}",
    ],
    theme: {
      extend: {},
    },
    plugins: [],
  }
  

4. tRPC适配改造 #

• 替换API入口：新建app/api/trpc/[trpc]/route.ts（替代原pages/api/trpc/[trpc].ts），示例代码：

  import { fetchRequestHandler } from '@trpc/server/adapters/fetch';
  import { appRouter } from '@/server/router';
  import { createTRPCContext } from '@/server/trpc';
  
  const handler = (req: Request) =>
    fetchRequestHandler({
      endpoint: '/api/trpc',
      req,
      router: appRouter,
      createContext: createTRPCContext,
    });
  
  export { handler as GET, handler as POST };
  

• 更新客户端配置：新建utils/trpc.ts，同时支持服务器组件与客户端组件：

  // 客户端组件用tRPC实例
  import { createTRPCReact } from '@trpc/react-query';
  import type { AppRouter } from '@/server/router';
  export const trpc = createTRPCReact<AppRouter>({});
  
  // 服务器组件用直接调用的caller
  import { httpBatchLink } from '@trpc/client';
  import { createTRPCContext } from '@/server/trpc';
  import { appRouter } from '@/server/router';
  export const serverTRPC = appRouter.createCaller(await createTRPCContext({}));
  

• 在app/layout.tsx中添加tRPC Provider（注意用'use client'标记Provider包裹的代码块，因为Provider是客户端组件）

5. 页面组件逻辑迁移 #

• 区分服务器组件与客户端组件：无交互逻辑的页面默认用服务器组件（无需'use client'），直接调用serverTRPC获取数据；需交互的组件添加'use client'指令，使用trpc.useQuery等客户端钩子
• 替换getServerSideProps/getStaticProps：服务器组件中直接写异步逻辑获取数据替代getServerSideProps；静态生成用generateStaticParams配合revalidate属性实现

6. 测试与验证 #

• 逐个页面验证路由跳转、数据渲染、样式显示是否正常
• 检查控制台兼容性警告，针对性调整代码
• 验证tRPC接口通信，确保客户端与服务器端数据交互无误

内容的提问来源于stack exchange，提问作者Si 12