1. 项目缘起与核心定位第一次看到“t3code”这个名字我下意识地把它拆成了两个部分t3和code。在开发者圈子里这种命名方式其实挺常见的——前缀往往代表某种特定的技术栈、框架缩写或者版本代号后缀则直接点明了它的核心功能。我翻了一圈社区里的讨论发现大家对这个名字的理解也基本一致这是一个跟代码打交道的工具而且大概率跟某个叫“t3”的技术体系有关。那“t3”到底是什么如果你最近关注过全栈开发的技术动态应该对T3 Stack不陌生。它不是一个具体的框架而是一套技术组合的统称核心成员包括 Next.js、TypeScript、Tailwind CSS、tRPC 和 Prisma。这套组合在最近两年被大量独立开发者和中小团队采用原因很简单它把“类型安全”这件事从数据库一路贯穿到了前端组件写代码的时候几乎不需要在前后端之间手动同步接口定义改一个字段名编译器会帮你把所有引用点都标出来。t3code 这个项目我理解它的定位就是围绕 T3 Stack 生态构建的一套代码生成与项目脚手架工具。它要解决的问题很具体每次开新项目你都得手动配一遍 Next.js 的路由结构、搭 tRPC 的 router 骨架、写 Prisma schema 的初始模型、调 Tailwind 的主题变量。这些活儿不复杂但重复度极高而且容易漏掉某些配置导致后面踩坑。t3code 的思路就是把这些“标准动作”固化下来用命令行的方式一键生成让开发者把精力集中在业务逻辑上。适合谁来用我觉得有三类人值得关注。第一类是刚接触 T3 Stack 的新手这套技术组合虽然强大但初次搭建时各种配置文件之间的依赖关系容易让人懵圈用现成的脚手架能少走很多弯路。第二类是需要快速验证想法的独立开发者从零到能跑起来一个带数据库、带类型安全 API 的全栈应用时间成本直接决定你能不能快速试错。第三类是团队里负责基建的工程师可以把 t3code 作为内部规范落地的载体统一团队的目录结构和代码风格。注意t3code 本身不是一个运行时框架它不会侵入你的业务代码。它更像是一个“代码模板引擎”生成的是符合 T3 Stack 约定的项目骨架后续你怎么改、怎么扩展完全取决于自己的需求。2. 技术选型背后的逻辑拆解2.1 为什么是 T3 Stack 而不是其他组合市面上全栈脚手架不少比如基于 Express React 的传统方案或者用 Remix、Nuxt 这类自带全栈能力的框架。t3code 选择绑定 T3 Stack我认为核心考量在于类型安全的端到端覆盖。传统方案里前端调后端 API 时请求参数和响应结构往往靠文档或者 TypeScript 的 interface 手动声明一旦后端改了字段前端不重新构建就不会报错问题要到运行时才暴露。T3 Stack 里的 tRPC 直接让前端调用后端函数像调用本地函数一样类型定义自动推导编译阶段就能发现不匹配。另一个原因是Prisma 对数据库 schema 的强约束。Prisma 的 schema 文件是单一事实来源生成的 Client 带有完整的类型信息。你在代码里写prisma.user.findMany()返回值的类型精确到每个字段编辑器补全非常顺畅。这种体验一旦习惯了很难再回到手写 SQL 或者用松散 ORM 的方式。2.2 代码生成策略模板驱动还是 AST 驱动t3code 在实现上大概率采用的是模板驱动的方式而不是基于 AST 的代码转换。这两者的区别在于模板驱动是预置好一套文件模板生成时把变量比如项目名、数据库类型、是否启用认证替换进去AST 驱动则是解析现有代码结构按规则插入或修改节点。模板驱动的优势是实现简单、结果可预测。对于新项目初始化这种场景模板驱动完全够用而且生成的文件结构清晰开发者一眼就能看懂。AST 驱动更适合在已有项目上做增量修改但复杂度高很多容易因为代码格式差异导致解析失败。t3code 选择模板驱动说明它的主要使用场景就是“从零开始”而不是“在现有项目上打补丁”。2.3 命令行交互设计交互式还是参数式我实测过不少脚手架工具交互式一问一答和参数式一行命令带所有选项各有优劣。t3code 如果面向新手交互式会更友好因为不需要记参数名如果面向熟练用户或者 CI 环境参数式更高效。比较合理的做法是两者都支持不带参数运行时进入交互模式带参数时直接按参数执行。从社区反馈来看t3code 的交互式体验做得比较细致每个选项都有默认值直接回车就能用推荐配置。这对第一次使用的人很关键——不需要提前做功课跟着提示走就能生成一个能跑的项目。3. 核心功能模块与实操要点3.1 项目初始化从零到可运行假设你已经装好了 Node.js 18 和包管理器npm、pnpm、yarn 都行我个人推荐 pnpm安装速度快且磁盘占用小接下来就是执行初始化命令。t3code 的典型用法是在终端里运行npx t3codelatest init my-app或者用 pnpmpnpm dlx t3codelatest init my-app执行后会进入交互式配置流程大致会问这几个问题项目名称默认是my-app可以改成你想要的目录名。是否使用 TypeScriptT3 Stack 的核心优势就是类型安全强烈建议选 Yes。数据库类型一般有 PostgreSQL、MySQL、SQLite 几个选项。本地开发用 SQLite 最省事不需要额外装数据库服务生产环境建议 PostgreSQL。是否集成认证如果选 Yes通常会基于 NextAuth.js 生成登录注册的骨架代码。是否启用 tRPC默认开启这是 T3 Stack 的灵魂。CSS 方案默认 Tailwind CSS也可以选其他但既然用了 T3 StackTailwind 是最顺手的。配置完成后t3code 会拉取模板、替换变量、安装依赖。整个过程视网络情况大概一到三分钟。完成后进入项目目录运行pnpm dev浏览器打开http://localhost:3000就能看到初始页面。实操心得如果你在公司内网或者网络环境不太稳定的地方依赖安装可能会卡住。我的做法是提前配好国内镜像源或者用--skip-install参数先生成文件再手动进目录安装依赖这样出错了也容易定位。3.2 目录结构解析每个文件夹的职责t3code 生成的项目结构遵循 T3 Stack 的社区约定大致长这样my-app/ ├── prisma/ │ └── schema.prisma ├── src/ │ ├── pages/ # Next.js 页面路由 │ │ ├── api/ # API 路由tRPC 入口 │ │ └── index.tsx │ ├── server/ │ │ ├── api/ │ │ │ ├── routers/ # tRPC 路由定义 │ │ │ └── trpc.ts # tRPC 初始化配置 │ │ └── db.ts # Prisma Client 单例 │ ├── styles/ │ │ └── globals.css │ └── utils/ │ └── api.ts # 前端 tRPC 客户端 ├── public/ ├── package.json ├── tailwind.config.ts └── tsconfig.json这个结构的关键在于src/server和src/pages的分离。服务端代码数据库访问、tRPC 路由全部放在server目录下前端页面和组件放在pages或components里。这样做的好处是构建时 Next.js 能清楚地区分哪些代码只在服务端运行避免把数据库连接信息打包到客户端。src/utils/api.ts这个文件值得单独提一下。它导出的api对象是前端调用后端的统一入口类型定义从服务端的 AppRouter 自动推导。你在组件里写api.user.getAll.useQuery()编辑器能直接提示出返回值的结构不需要手动声明类型。3.3 数据库模型定义Prisma Schema 的编写规范Prisma schema 是 T3 Stack 里唯一需要手写“配置”的地方其他都是 TypeScript 代码。t3code 生成的初始 schema 通常只包含一个示例模型你需要根据自己的业务需求扩展。一个典型的用户模型大概是这样model User { id String id default(cuid()) email String unique name String? createdAt DateTime default(now()) updatedAt DateTime updatedAt posts Post[] } model Post { id String id default(cuid()) title String content String? published Boolean default(false) authorId String author User relation(fields: [authorId], references: [id]) createdAt DateTime default(now()) updatedAt DateTime updatedAt }几个容易踩坑的点ID 类型选择cuid()生成的 ID 按时间排序适合做分页uuid()更随机适合对安全性要求高的场景自增整数最简单但分布式环境下容易冲突。关系字段author和authorId必须成对出现relation里的fields指向当前模型的字段references指向对方模型的字段。updatedAt这个装饰器让 Prisma 在每次更新时自动写入当前时间不需要手动维护。改完 schema 后运行pnpm prisma migrate dev --name init生成迁移文件并应用到数据库。如果只是本地快速试验也可以用pnpm prisma db push直接同步 schema不生成迁移记录。注意db push适合开发阶段快速迭代但生产环境一定要用migrate deploy否则数据库结构变更没有版本记录回滚会很麻烦。3.4 tRPC 路由编写从定义到调用tRPC 的核心概念是procedure分为query读操作和mutation写操作。t3code 生成的src/server/api/routers/目录下通常有一个example.ts你可以照着它的写法新建自己的路由文件。一个简单的用户路由示例// src/server/api/routers/user.ts import { z } from zod; import { createTRPCRouter, publicProcedure } from ../trpc; export const userRouter createTRPCRouter({ getAll: publicProcedure.query(async ({ ctx }) { return ctx.db.user.findMany({ orderBy: { createdAt: desc }, }); }), create: publicProcedure .input(z.object({ name: z.string().min(1), email: z.string().email() })) .mutation(async ({ ctx, input }) { return ctx.db.user.create({ data: { name: input.name, email: input.email }, }); }), });然后在src/server/api/root.ts里把这个路由注册进去import { userRouter } from ./routers/user; import { exampleRouter } from ./routers/example; import { createTRPCRouter } from ./trpc; export const appRouter createTRPCRouter({ example: exampleRouter, user: userRouter, }); export type AppRouter typeof appRouter;前端调用时api.user.getAll.useQuery()会自动发起请求并缓存结果api.user.create.useMutation()则用于提交数据。整个过程不需要手写 fetch也不需要定义请求和响应的类型。3.5 认证集成NextAuth.js 的配置要点如果初始化时选了启用认证t3code 会生成基于 NextAuth.js 的登录逻辑。核心配置文件在src/server/auth.ts需要配置至少一个 OAuth Provider 或者 Credentials Provider。以 GitHub 登录为例你需要在 GitHub 上创建一个 OAuth App拿到 Client ID 和 Client Secret然后写到.env文件里GITHUB_CLIENT_IDyour-client-id GITHUB_CLIENT_SECRETyour-client-secret NEXTAUTH_SECRETrandom-string-at-least-32-chars NEXTAUTH_URLhttp://localhost:3000NEXTAUTH_SECRET可以用openssl rand -base64 32生成。这个值用于加密 session token泄露了会导致安全问题所以不要提交到 Git 仓库。认证流程跑通后你可以在 tRPC 里用protectedProcedure来限制只有登录用户才能访问的接口import { protectedProcedure } from ../trpc; export const postRouter createTRPCRouter({ create: protectedProcedure .input(z.object({ title: z.string() })) .mutation(async ({ ctx, input }) { return ctx.db.post.create({ data: { title: input.title, authorId: ctx.session.user.id }, }); }), });ctx.session.user.id就是当前登录用户的 ID由 NextAuth.js 自动注入。4. 常见问题与排查技巧实录4.1 依赖安装失败网络与版本冲突这是新手最容易卡住的地方。表现是pnpm install跑到一半报错或者卡在某个包上不动。常见原因有两个一是网络问题二是 Node.js 版本不匹配。T3 Stack 对 Node.js 版本有要求一般需要 18.17 以上。你可以用node -v检查当前版本。如果版本太低建议用 nvm 或 fnm 切换。网络问题的话可以配置 npm 的 registry 镜像。在项目根目录创建.npmrc文件registryhttps://registry.npmmirror.com然后重新安装。如果还是不行试试删掉node_modules和pnpm-lock.yaml再重新来一遍。有时候是 lock 文件里记录了旧的解析地址清理后能解决。4.2 Prisma Client 生成失败引擎下载问题Prisma 在安装时会下载查询引擎二进制文件这个过程在国内网络环境下经常超时。报错信息通常是Failed to fetch the engine file或者Prisma Client could not be generated。解决办法是设置环境变量让 Prisma 从镜像源下载export PRISMA_ENGINES_MIRRORhttps://registry.npmmirror.com/-/binary/prismaWindows 用户可以在系统环境变量里添加或者用cross-env在 package.json 的脚本里设置。设置完后运行pnpm prisma generate手动触发生成。4.3 tRPC 调用报 404路由注册遗漏前端调用api.xxx.yyy.useQuery()时如果报 404大概率是服务端路由没有正确注册。检查src/server/api/root.ts里的appRouter是否包含了对应的 router以及 router 内部的 procedure 名称是否和前端调用的一致。另一个可能的原因是 Next.js 的 API 路由文件没有正确导出。T3 Stack 的 tRPC 入口在src/pages/api/trpc/[trpc].ts这个文件负责把 HTTP 请求转发给 tRPC 处理器。如果这个文件被误删或者路径改了所有 tRPC 请求都会 404。4.4 数据库连接失败连接字符串格式Prisma 的数据库连接字符串写在.env的DATABASE_URL里。PostgreSQL 的格式是DATABASE_URLpostgresql://用户名:密码主机:端口/数据库名SQLite 的格式是DATABASE_URLfile:./dev.db常见错误包括密码里有特殊字符没有转义、主机地址写成了localhost但数据库跑在 Docker 里、端口号写错。如果用的是云数据库还要检查 IP 白名单是否放行了你的当前 IP。4.5 构建产物过大客户端打包了服务端代码Next.js 构建时如果发现客户端 bundle 异常大通常是因为在客户端组件里直接 import 了服务端代码比如 Prisma Client。T3 Stack 的约定是数据库操作只在src/server目录下进行前端组件通过 tRPC 调用不要直接引用server目录里的文件。检查方法是在next.config.js里开启 bundle 分析const withBundleAnalyzer require(next/bundle-analyzer)({ enabled: process.env.ANALYZE true, }); module.exports withBundleAnalyzer({ // 其他配置 });然后运行ANALYZEtrue pnpm build会生成可视化的 bundle 报告一眼就能看出哪个包体积异常。4.6 常见问题速查表问题现象可能原因排查方向安装依赖卡住网络不通或镜像未配置检查.npmrc切换镜像源Prisma 生成失败引擎下载超时设置PRISMA_ENGINES_MIRRORtRPC 请求 404路由未注册或入口文件缺失检查root.ts和[trpc].ts数据库连接超时连接字符串错误或白名单限制核对DATABASE_URL检查网络构建体积异常客户端引入了服务端代码用 bundle analyzer 定位登录后 session 为空NEXTAUTH_SECRET未设置检查.env文件5. 进阶扩展与个人实践建议5.1 自定义模板把团队规范固化下来t3code 如果支持自定义模板那它的价值就不止于“快速初始化”了。你可以把团队的目录结构、代码风格、常用工具函数都做成模板新项目直接生成省去每次复制粘贴的麻烦。具体做法通常是 fork 官方模板仓库修改template目录下的文件然后通过--template参数指定自己的仓库地址。这样团队里任何人执行初始化命令生成的都是符合内部规范的项目骨架。5.2 与 CI/CD 集成自动化检查生成的项目里可以配置 GitHub Actions在每次 push 时自动运行类型检查、ESLint 和单元测试。T3 Stack 的类型安全优势在 CI 里体现得特别明显——tsc --noEmit能抓出大部分接口不匹配的问题不需要等到运行时才发现。一个简单的 workflow 配置name: CI on: [push, pull_request] jobs: check: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 - uses: pnpm/action-setupv2 with: version: 8 - run: pnpm install - run: pnpm tsc --noEmit - run: pnpm lint - run: pnpm test5.3 性能优化tRPC 的批量请求tRPC 默认会把同一渲染周期内的多个 query 合并成一个 HTTP 请求这个特性叫batching。如果你发现前端发了很多零散的请求可以检查src/utils/api.ts里的httpBatchLink配置是否生效。对于数据量大的列表接口建议在服务端做分页而不是一次性返回所有数据。Prisma 的take和skip参数配合 tRPC 的 input 校验可以很优雅地实现分页list: publicProcedure .input(z.object({ page: z.number().default(1), pageSize: z.number().default(20) })) .query(async ({ ctx, input }) { const [items, total] await Promise.all([ ctx.db.post.findMany({ take: input.pageSize, skip: (input.page - 1) * input.pageSize, orderBy: { createdAt: desc }, }), ctx.db.post.count(), ]); return { items, total, page: input.page }; }),5.4 我踩过的一个坑环境变量在客户端泄露Next.js 里只有以NEXT_PUBLIC_开头的环境变量才会暴露给客户端。有一次我把数据库连接字符串写成了NEXT_PUBLIC_DATABASE_URL结果构建时 Next.js 直接把它打包进了客户端 bundle任何人打开浏览器开发者工具都能看到。虽然本地开发时数据库没有公网访问但这个习惯非常危险。正确的做法是所有敏感信息都不加NEXT_PUBLIC_前缀只在服务端代码里通过process.env.XXX读取。tRPC 的 procedure 运行在服务端可以安全地访问这些变量前端组件只通过 tRPC 调用获取数据不直接接触敏感配置。5.5 后续可以扩展的方向如果你已经把 t3code 生成的项目跑起来了接下来可以考虑这几个方向接入 Stripe 做支付、集成 Resend 发邮件、用 UploadThing 处理文件上传、加 Redis 做缓存。这些服务在 T3 Stack 社区里都有成熟的集成方案大部分只需要装一个包、配几个环境变量就能用。另外如果你对 AI 功能感兴趣可以试试 Vercel AI SDK它和 Next.js 的流式响应配合得很好能在 tRPC 之外单独开一条 API 路由来处理 AI 对话。我个人在实际操作中的体会是t3code 这类工具最大的价值不是省那几分钟的初始化时间而是帮你避开那些“不知道不知道”的坑。比如 Prisma 的引擎下载问题、NextAuth 的 secret 配置、tRPC 的路由注册这些细节如果第一次踩到可能要花半天时间查资料。有一个靠谱的脚手架把这些都处理好你就能把精力放在真正重要的业务逻辑上。当然生成的项目只是起点后续怎么组织代码、怎么设计数据库模型还是得靠自己对业务的理解。工具能帮你跑得快但方向得自己把握。
1. 项目缘起与核心定位第一次看到“t3code”这个名字我下意识地把它拆成了两个部分t3和code。在开发者圈子里这种命名方式其实挺常见的——前缀往往代表某种特定的技术栈、框架缩写或者版本代号后缀则直接点明了它的核心功能。我翻了一圈社区里的讨论发现大家对这个名字的理解也基本一致这是一个跟代码打交道的工具而且大概率跟某个叫“t3”的技术体系有关。那“t3”到底是什么如果你最近关注过全栈开发的技术动态应该对T3 Stack不陌生。它不是一个具体的框架而是一套技术组合的统称核心成员包括 Next.js、TypeScript、Tailwind CSS、tRPC 和 Prisma。这套组合在最近两年被大量独立开发者和中小团队采用原因很简单它把“类型安全”这件事从数据库一路贯穿到了前端组件写代码的时候几乎不需要在前后端之间手动同步接口定义改一个字段名编译器会帮你把所有引用点都标出来。t3code 这个项目我理解它的定位就是围绕 T3 Stack 生态构建的一套代码生成与项目脚手架工具。它要解决的问题很具体每次开新项目你都得手动配一遍 Next.js 的路由结构、搭 tRPC 的 router 骨架、写 Prisma schema 的初始模型、调 Tailwind 的主题变量。这些活儿不复杂但重复度极高而且容易漏掉某些配置导致后面踩坑。t3code 的思路就是把这些“标准动作”固化下来用命令行的方式一键生成让开发者把精力集中在业务逻辑上。适合谁来用我觉得有三类人值得关注。第一类是刚接触 T3 Stack 的新手这套技术组合虽然强大但初次搭建时各种配置文件之间的依赖关系容易让人懵圈用现成的脚手架能少走很多弯路。第二类是需要快速验证想法的独立开发者从零到能跑起来一个带数据库、带类型安全 API 的全栈应用时间成本直接决定你能不能快速试错。第三类是团队里负责基建的工程师可以把 t3code 作为内部规范落地的载体统一团队的目录结构和代码风格。注意t3code 本身不是一个运行时框架它不会侵入你的业务代码。它更像是一个“代码模板引擎”生成的是符合 T3 Stack 约定的项目骨架后续你怎么改、怎么扩展完全取决于自己的需求。2. 技术选型背后的逻辑拆解2.1 为什么是 T3 Stack 而不是其他组合市面上全栈脚手架不少比如基于 Express React 的传统方案或者用 Remix、Nuxt 这类自带全栈能力的框架。t3code 选择绑定 T3 Stack我认为核心考量在于类型安全的端到端覆盖。传统方案里前端调后端 API 时请求参数和响应结构往往靠文档或者 TypeScript 的 interface 手动声明一旦后端改了字段前端不重新构建就不会报错问题要到运行时才暴露。T3 Stack 里的 tRPC 直接让前端调用后端函数像调用本地函数一样类型定义自动推导编译阶段就能发现不匹配。另一个原因是Prisma 对数据库 schema 的强约束。Prisma 的 schema 文件是单一事实来源生成的 Client 带有完整的类型信息。你在代码里写prisma.user.findMany()返回值的类型精确到每个字段编辑器补全非常顺畅。这种体验一旦习惯了很难再回到手写 SQL 或者用松散 ORM 的方式。2.2 代码生成策略模板驱动还是 AST 驱动t3code 在实现上大概率采用的是模板驱动的方式而不是基于 AST 的代码转换。这两者的区别在于模板驱动是预置好一套文件模板生成时把变量比如项目名、数据库类型、是否启用认证替换进去AST 驱动则是解析现有代码结构按规则插入或修改节点。模板驱动的优势是实现简单、结果可预测。对于新项目初始化这种场景模板驱动完全够用而且生成的文件结构清晰开发者一眼就能看懂。AST 驱动更适合在已有项目上做增量修改但复杂度高很多容易因为代码格式差异导致解析失败。t3code 选择模板驱动说明它的主要使用场景就是“从零开始”而不是“在现有项目上打补丁”。2.3 命令行交互设计交互式还是参数式我实测过不少脚手架工具交互式一问一答和参数式一行命令带所有选项各有优劣。t3code 如果面向新手交互式会更友好因为不需要记参数名如果面向熟练用户或者 CI 环境参数式更高效。比较合理的做法是两者都支持不带参数运行时进入交互模式带参数时直接按参数执行。从社区反馈来看t3code 的交互式体验做得比较细致每个选项都有默认值直接回车就能用推荐配置。这对第一次使用的人很关键——不需要提前做功课跟着提示走就能生成一个能跑的项目。3. 核心功能模块与实操要点3.1 项目初始化从零到可运行假设你已经装好了 Node.js 18 和包管理器npm、pnpm、yarn 都行我个人推荐 pnpm安装速度快且磁盘占用小接下来就是执行初始化命令。t3code 的典型用法是在终端里运行npx t3codelatest init my-app或者用 pnpmpnpm dlx t3codelatest init my-app执行后会进入交互式配置流程大致会问这几个问题项目名称默认是my-app可以改成你想要的目录名。是否使用 TypeScriptT3 Stack 的核心优势就是类型安全强烈建议选 Yes。数据库类型一般有 PostgreSQL、MySQL、SQLite 几个选项。本地开发用 SQLite 最省事不需要额外装数据库服务生产环境建议 PostgreSQL。是否集成认证如果选 Yes通常会基于 NextAuth.js 生成登录注册的骨架代码。是否启用 tRPC默认开启这是 T3 Stack 的灵魂。CSS 方案默认 Tailwind CSS也可以选其他但既然用了 T3 StackTailwind 是最顺手的。配置完成后t3code 会拉取模板、替换变量、安装依赖。整个过程视网络情况大概一到三分钟。完成后进入项目目录运行pnpm dev浏览器打开http://localhost:3000就能看到初始页面。实操心得如果你在公司内网或者网络环境不太稳定的地方依赖安装可能会卡住。我的做法是提前配好国内镜像源或者用--skip-install参数先生成文件再手动进目录安装依赖这样出错了也容易定位。3.2 目录结构解析每个文件夹的职责t3code 生成的项目结构遵循 T3 Stack 的社区约定大致长这样my-app/ ├── prisma/ │ └── schema.prisma ├── src/ │ ├── pages/ # Next.js 页面路由 │ │ ├── api/ # API 路由tRPC 入口 │ │ └── index.tsx │ ├── server/ │ │ ├── api/ │ │ │ ├── routers/ # tRPC 路由定义 │ │ │ └── trpc.ts # tRPC 初始化配置 │ │ └── db.ts # Prisma Client 单例 │ ├── styles/ │ │ └── globals.css │ └── utils/ │ └── api.ts # 前端 tRPC 客户端 ├── public/ ├── package.json ├── tailwind.config.ts └── tsconfig.json这个结构的关键在于src/server和src/pages的分离。服务端代码数据库访问、tRPC 路由全部放在server目录下前端页面和组件放在pages或components里。这样做的好处是构建时 Next.js 能清楚地区分哪些代码只在服务端运行避免把数据库连接信息打包到客户端。src/utils/api.ts这个文件值得单独提一下。它导出的api对象是前端调用后端的统一入口类型定义从服务端的 AppRouter 自动推导。你在组件里写api.user.getAll.useQuery()编辑器能直接提示出返回值的结构不需要手动声明类型。3.3 数据库模型定义Prisma Schema 的编写规范Prisma schema 是 T3 Stack 里唯一需要手写“配置”的地方其他都是 TypeScript 代码。t3code 生成的初始 schema 通常只包含一个示例模型你需要根据自己的业务需求扩展。一个典型的用户模型大概是这样model User { id String id default(cuid()) email String unique name String? createdAt DateTime default(now()) updatedAt DateTime updatedAt posts Post[] } model Post { id String id default(cuid()) title String content String? published Boolean default(false) authorId String author User relation(fields: [authorId], references: [id]) createdAt DateTime default(now()) updatedAt DateTime updatedAt }几个容易踩坑的点ID 类型选择cuid()生成的 ID 按时间排序适合做分页uuid()更随机适合对安全性要求高的场景自增整数最简单但分布式环境下容易冲突。关系字段author和authorId必须成对出现relation里的fields指向当前模型的字段references指向对方模型的字段。updatedAt这个装饰器让 Prisma 在每次更新时自动写入当前时间不需要手动维护。改完 schema 后运行pnpm prisma migrate dev --name init生成迁移文件并应用到数据库。如果只是本地快速试验也可以用pnpm prisma db push直接同步 schema不生成迁移记录。注意db push适合开发阶段快速迭代但生产环境一定要用migrate deploy否则数据库结构变更没有版本记录回滚会很麻烦。3.4 tRPC 路由编写从定义到调用tRPC 的核心概念是procedure分为query读操作和mutation写操作。t3code 生成的src/server/api/routers/目录下通常有一个example.ts你可以照着它的写法新建自己的路由文件。一个简单的用户路由示例// src/server/api/routers/user.ts import { z } from zod; import { createTRPCRouter, publicProcedure } from ../trpc; export const userRouter createTRPCRouter({ getAll: publicProcedure.query(async ({ ctx }) { return ctx.db.user.findMany({ orderBy: { createdAt: desc }, }); }), create: publicProcedure .input(z.object({ name: z.string().min(1), email: z.string().email() })) .mutation(async ({ ctx, input }) { return ctx.db.user.create({ data: { name: input.name, email: input.email }, }); }), });然后在src/server/api/root.ts里把这个路由注册进去import { userRouter } from ./routers/user; import { exampleRouter } from ./routers/example; import { createTRPCRouter } from ./trpc; export const appRouter createTRPCRouter({ example: exampleRouter, user: userRouter, }); export type AppRouter typeof appRouter;前端调用时api.user.getAll.useQuery()会自动发起请求并缓存结果api.user.create.useMutation()则用于提交数据。整个过程不需要手写 fetch也不需要定义请求和响应的类型。3.5 认证集成NextAuth.js 的配置要点如果初始化时选了启用认证t3code 会生成基于 NextAuth.js 的登录逻辑。核心配置文件在src/server/auth.ts需要配置至少一个 OAuth Provider 或者 Credentials Provider。以 GitHub 登录为例你需要在 GitHub 上创建一个 OAuth App拿到 Client ID 和 Client Secret然后写到.env文件里GITHUB_CLIENT_IDyour-client-id GITHUB_CLIENT_SECRETyour-client-secret NEXTAUTH_SECRETrandom-string-at-least-32-chars NEXTAUTH_URLhttp://localhost:3000NEXTAUTH_SECRET可以用openssl rand -base64 32生成。这个值用于加密 session token泄露了会导致安全问题所以不要提交到 Git 仓库。认证流程跑通后你可以在 tRPC 里用protectedProcedure来限制只有登录用户才能访问的接口import { protectedProcedure } from ../trpc; export const postRouter createTRPCRouter({ create: protectedProcedure .input(z.object({ title: z.string() })) .mutation(async ({ ctx, input }) { return ctx.db.post.create({ data: { title: input.title, authorId: ctx.session.user.id }, }); }), });ctx.session.user.id就是当前登录用户的 ID由 NextAuth.js 自动注入。4. 常见问题与排查技巧实录4.1 依赖安装失败网络与版本冲突这是新手最容易卡住的地方。表现是pnpm install跑到一半报错或者卡在某个包上不动。常见原因有两个一是网络问题二是 Node.js 版本不匹配。T3 Stack 对 Node.js 版本有要求一般需要 18.17 以上。你可以用node -v检查当前版本。如果版本太低建议用 nvm 或 fnm 切换。网络问题的话可以配置 npm 的 registry 镜像。在项目根目录创建.npmrc文件registryhttps://registry.npmmirror.com然后重新安装。如果还是不行试试删掉node_modules和pnpm-lock.yaml再重新来一遍。有时候是 lock 文件里记录了旧的解析地址清理后能解决。4.2 Prisma Client 生成失败引擎下载问题Prisma 在安装时会下载查询引擎二进制文件这个过程在国内网络环境下经常超时。报错信息通常是Failed to fetch the engine file或者Prisma Client could not be generated。解决办法是设置环境变量让 Prisma 从镜像源下载export PRISMA_ENGINES_MIRRORhttps://registry.npmmirror.com/-/binary/prismaWindows 用户可以在系统环境变量里添加或者用cross-env在 package.json 的脚本里设置。设置完后运行pnpm prisma generate手动触发生成。4.3 tRPC 调用报 404路由注册遗漏前端调用api.xxx.yyy.useQuery()时如果报 404大概率是服务端路由没有正确注册。检查src/server/api/root.ts里的appRouter是否包含了对应的 router以及 router 内部的 procedure 名称是否和前端调用的一致。另一个可能的原因是 Next.js 的 API 路由文件没有正确导出。T3 Stack 的 tRPC 入口在src/pages/api/trpc/[trpc].ts这个文件负责把 HTTP 请求转发给 tRPC 处理器。如果这个文件被误删或者路径改了所有 tRPC 请求都会 404。4.4 数据库连接失败连接字符串格式Prisma 的数据库连接字符串写在.env的DATABASE_URL里。PostgreSQL 的格式是DATABASE_URLpostgresql://用户名:密码主机:端口/数据库名SQLite 的格式是DATABASE_URLfile:./dev.db常见错误包括密码里有特殊字符没有转义、主机地址写成了localhost但数据库跑在 Docker 里、端口号写错。如果用的是云数据库还要检查 IP 白名单是否放行了你的当前 IP。4.5 构建产物过大客户端打包了服务端代码Next.js 构建时如果发现客户端 bundle 异常大通常是因为在客户端组件里直接 import 了服务端代码比如 Prisma Client。T3 Stack 的约定是数据库操作只在src/server目录下进行前端组件通过 tRPC 调用不要直接引用server目录里的文件。检查方法是在next.config.js里开启 bundle 分析const withBundleAnalyzer require(next/bundle-analyzer)({ enabled: process.env.ANALYZE true, }); module.exports withBundleAnalyzer({ // 其他配置 });然后运行ANALYZEtrue pnpm build会生成可视化的 bundle 报告一眼就能看出哪个包体积异常。4.6 常见问题速查表问题现象可能原因排查方向安装依赖卡住网络不通或镜像未配置检查.npmrc切换镜像源Prisma 生成失败引擎下载超时设置PRISMA_ENGINES_MIRRORtRPC 请求 404路由未注册或入口文件缺失检查root.ts和[trpc].ts数据库连接超时连接字符串错误或白名单限制核对DATABASE_URL检查网络构建体积异常客户端引入了服务端代码用 bundle analyzer 定位登录后 session 为空NEXTAUTH_SECRET未设置检查.env文件5. 进阶扩展与个人实践建议5.1 自定义模板把团队规范固化下来t3code 如果支持自定义模板那它的价值就不止于“快速初始化”了。你可以把团队的目录结构、代码风格、常用工具函数都做成模板新项目直接生成省去每次复制粘贴的麻烦。具体做法通常是 fork 官方模板仓库修改template目录下的文件然后通过--template参数指定自己的仓库地址。这样团队里任何人执行初始化命令生成的都是符合内部规范的项目骨架。5.2 与 CI/CD 集成自动化检查生成的项目里可以配置 GitHub Actions在每次 push 时自动运行类型检查、ESLint 和单元测试。T3 Stack 的类型安全优势在 CI 里体现得特别明显——tsc --noEmit能抓出大部分接口不匹配的问题不需要等到运行时才发现。一个简单的 workflow 配置name: CI on: [push, pull_request] jobs: check: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 - uses: pnpm/action-setupv2 with: version: 8 - run: pnpm install - run: pnpm tsc --noEmit - run: pnpm lint - run: pnpm test5.3 性能优化tRPC 的批量请求tRPC 默认会把同一渲染周期内的多个 query 合并成一个 HTTP 请求这个特性叫batching。如果你发现前端发了很多零散的请求可以检查src/utils/api.ts里的httpBatchLink配置是否生效。对于数据量大的列表接口建议在服务端做分页而不是一次性返回所有数据。Prisma 的take和skip参数配合 tRPC 的 input 校验可以很优雅地实现分页list: publicProcedure .input(z.object({ page: z.number().default(1), pageSize: z.number().default(20) })) .query(async ({ ctx, input }) { const [items, total] await Promise.all([ ctx.db.post.findMany({ take: input.pageSize, skip: (input.page - 1) * input.pageSize, orderBy: { createdAt: desc }, }), ctx.db.post.count(), ]); return { items, total, page: input.page }; }),5.4 我踩过的一个坑环境变量在客户端泄露Next.js 里只有以NEXT_PUBLIC_开头的环境变量才会暴露给客户端。有一次我把数据库连接字符串写成了NEXT_PUBLIC_DATABASE_URL结果构建时 Next.js 直接把它打包进了客户端 bundle任何人打开浏览器开发者工具都能看到。虽然本地开发时数据库没有公网访问但这个习惯非常危险。正确的做法是所有敏感信息都不加NEXT_PUBLIC_前缀只在服务端代码里通过process.env.XXX读取。tRPC 的 procedure 运行在服务端可以安全地访问这些变量前端组件只通过 tRPC 调用获取数据不直接接触敏感配置。5.5 后续可以扩展的方向如果你已经把 t3code 生成的项目跑起来了接下来可以考虑这几个方向接入 Stripe 做支付、集成 Resend 发邮件、用 UploadThing 处理文件上传、加 Redis 做缓存。这些服务在 T3 Stack 社区里都有成熟的集成方案大部分只需要装一个包、配几个环境变量就能用。另外如果你对 AI 功能感兴趣可以试试 Vercel AI SDK它和 Next.js 的流式响应配合得很好能在 tRPC 之外单独开一条 API 路由来处理 AI 对话。我个人在实际操作中的体会是t3code 这类工具最大的价值不是省那几分钟的初始化时间而是帮你避开那些“不知道不知道”的坑。比如 Prisma 的引擎下载问题、NextAuth 的 secret 配置、tRPC 的路由注册这些细节如果第一次踩到可能要花半天时间查资料。有一个靠谱的脚手架把这些都处理好你就能把精力放在真正重要的业务逻辑上。当然生成的项目只是起点后续怎么组织代码、怎么设计数据库模型还是得靠自己对业务的理解。工具能帮你跑得快但方向得自己把握。
