t3code。单看这个名字你可能会以为是我给哪个开源工具随手起的代号。实际上它是我最近一个全栈 Web 项目的工作标题含义很直接用 T3 Stack 写出来的代码。T3 Stack 在圈子里已经不算新鲜了核心是 TypeScript、Tailwind CSS、tRPC 这三样再配上 Next.js、Prisma、NextAuth.js组成一套前后端通吃的方案。这篇文章就把我从初始化 t3code 到部署上线的完整过程做个记录包括我为什么这样选型、哪一步最容易踩坑、以及最终工程长什么样。如果你正在研究全栈开发或者想从传统的 REST API 前端脚手架切换到端到端类型安全的方案这篇应该能给你一些实际参考。1. 为什么把项目代号定为 t3codeT3 Stack 组合背后的逻辑1.1 T3 不是在凑字母而是一套可落地的全栈框架T3 Stack 的定位是“追求简单、模块化和全栈类型安全的 Web 开发方式”名字拆开就是 TypeScript、Tailwind CSS、tRPC 三样。围绕这条主线create-t3-app 默认又帮你把 Next.js、Prisma、NextAuth.js 一起接进来。第一次接触的人很容易被吓到以为要把六七个框架同时学会才能动手。但实际上这套组合的核心思路是让每一层都共享同一种“类型”语言Prisma 生成的数据库类型、tRPC 的输入输出类型、前端 React Query 拿到的数据形状全部由编译器盯着。前端调用一个接口返回字段不对编辑器当场标红根本不用跑到浏览器里看控制台。我选择 t3code 的核心场景是做一个面向小团队的内部知识库工具功能包含用户登录、笔记管理、标签分类和收藏。这类应用有很强的 CRUD 特征数据模型清晰前后端交互频繁恰恰是 T3 Stack 最舒服的地带。如果换成内容展示型站点或对 SEO 要求极高服务端渲染和静态生成权重要更大T3 的收益反而不明显。所以第一个原则是先看清自己的项目类型再决定要不要上这套组合别因为它热门就无脑跟。1.2 端到端类型安全为什么值得付出一遍学习成本传统的开发方式是后端写 REST 接口、前端根据接口文档手动定义类型。接口一多文档先跟不上类型再跟不上联调时发现问题只能靠肉眼盯。我在 t3code 里最直观的感受是接口层被 tRPC“抹平”了函数名就是从浏览器直接调用的函数名参数和返回值类型在前后端之间自动推导。改一个 Prisma 字段Schema 变了tRPC 的返回类型跟着变前端页面里用到这个字段的地方全部标红。早期这种全链路联动让我不太适应因为以前总习惯“前端先不管后端返回什么算什么”现在被迫把数据形状想清楚再动手。但是这种约束在项目中期会变成一种很强的保护。t3code 的知识库模型后来大概迭代了三轮笔记加了发布状态、标签改成多对多关系、用户加了收藏表都是先在 Schema 层改然后顺着 TypeScript 的报错一路清过去。比起以前那种“接口改了没人知道线上运行时才发现字段 undefined”的体验这点学习成本我觉得相当值。当然代价也很明确你必须在项目里保持 TypeScript 的纯度不能出现 anystring 或 any 泄漏否则类型安全链条会在某个环节断掉。1.3 t3code 项目要解决的真实场景t3code 不是一个纯玩具项目它要解决的具体问题是团队成员散落多地内部资料分散在聊天记录、共享网盘、本地文档里没人能快速找到一份旧方案的原稿。所以我给它的定位是带账号体系的轻量知识库核心路径是用户登录 → 查看自己的笔记列表 → 新建/编辑笔记 → 给笔记打标签 → 按标签检索。权限上普通用户只能管理自己的笔记管理员可以查看全站笔记列表。这个范围不大不小刚好能把 T3 Stack 里 Prisma、tRPC、NextAuth 这几个核心模块都充分用起来又不会让工程量膨胀到后期没法收拾。如果你正打算用这套技术栈做自己的项目我建议也别一上来就追求大而全先把一条用户主链路走通比塞进十个无关功能要重要得多。2. 初始化 t3codecreate-t3-app 的选项与初始化后的骨架2.1 创建项目命令与交互选项初始化用的是官方脚手架一条命令pnpm create t3-applatest t3code执行之后会进入交互式问答这里面的每一个选项都值得认真读一遍而不是一路回车。我记得实际会依次问到是否使用 Tailwind CSS、tRPC、Prisma、NextAuth.js以及选择 App Router 还是 Pages Router。create-t3-app 的哲学是“按需添加复杂度”所以它只把自己擅长的组合当成默认不强制你一次性全上。我当时的勾选结果是Tailwind CSS 开、tRPC 开、Prisma 开、NextAuth.js 开Router 选 App Router。理由很简单t3code 需要数据库、需要接口、需要登录这四个模块没有一个是多余的。Cli 还会问 Import alias默认是~/*这个保持默认就好。选完之后它会自动安装依赖并初始化 Git 仓库整个过程大概几分钟依赖装完直接用。2.2 生成出来的目录结构每一层分别承担什么初始化完成的目录结构大致是这样的t3code/ ├── prisma/ │ └── schema.prisma ├── public/ ├── src/ │ ├── app/ │ ├── components/ │ ├── server/ │ ├── trpc/ │ └── styles/ ├── .env └── package.json这个结构很容易理解我拆开说prisma/schema.prisma是数据库模型的唯一事实来源后面所有表结构都从这改src/server放服务端相关的 Prisma 实例、NextAuth 配置、tRPC context 这些“后台逻辑”src/trpc里是 tRPC 服务端路由的根定义和前端 react hooks 的封装入口src/app是 App Router 下的页面和接口路由。我第一次看到这个结构时觉得也没什么特别但实际用下来发现它的好处是边界很清楚——服务端的东西全在server里前端调用统一走src/trpc/react不会出现那种页面文件里到处散落数据库操作的写法。2.3 环境变量的准备先弄干净再动手初始化完成后第一步永远不是跑 dev server而是配环境变量。create-t3-app 会生成一个.env.example里面列出了所有需要的变量你需要复制一份到.env然后逐个填。t3code 当时至少需要这几个DATABASE_URLpostgresql://user:passwordlocalhost:5432/t3code NEXTAUTH_SECRET随意生成一段足够长的随机字符串 NEXTAUTH_URLhttp://localhost:3000数据库我用的是 PostgreSQL也可以用 SQLite但如果准备部署生产环境我建议直接从 PostgreSQL 开始避免后面换库时被一些类型的差异拖累。NEXTAUTH_SECRET可以用openssl rand -base64 32生成。这里最容易踩的坑是把.env当成代码的一部分传进仓库我在自己项目里吃过一次亏后来直接在.gitignore里把.env加死把.env.example作为唯一模板提交上去这样队友克隆下来也知道要配哪些变量。3. 数据层设计Prisma Schema、迁移和种子数据3.1 从业务模型到 Schema 的实际转换t3code 的知识库模型在 Schema 层是这样设计的用户 User、笔记 Note、标签 Tag以及用户和笔记之间的收藏关系。一个用户可以有多个笔记一个笔记可以被多个用户收藏笔记和标签是多对多关系。Prisma 里多对多通常用隐式关系写两个模型各声明一个互相指向的数组字段就行model User { id String id default(cuid()) name String? email String? unique emailVerified DateTime? image String? accounts Account[] sessions Session[] notes Note[] favorites Favorite[] } model Note { id String id default(cuid()) title String content String published Boolean default(false) createdAt DateTime default(now()) updatedAt DateTime updatedAt authorId String author User relation(fields: [authorId], references: [id], onDelete: Cascade) favorites Favorite[] tags Tag[] } model Tag { id String id default(cuid()) name String unique notes Note[] } model Favorite { userId String user User relation(fields: [userId], references: [id], onDelete: Cascade) noteId String note Note relation(fields: [noteId], references: [id], onDelete: Cascade) id([userId, noteId]) }这里我特意把 Favorite 设计成显式中间表而不是在 User 和 Note 之间直接写多对多数组。原因是显式表以后可以继续扩展字段比如加一个createdAt记录收藏时机后面要做“最近收藏排序”就很容易。Prisma 的隐式多对多关系虽然写起来省事但想加字段的时候要回头改成显式表属于前期偷懒后期还债的典型。3.2 迁移、Generate 和 Seed 的配合方式Schema 写完下一步是同步到数据库npx prisma migrate dev --name init npx prisma generate第一条命令会在数据库里建表同时生成 migration 文件第二条命令生成 TypeScript 客户端让你能在代码里直接prisma.note.findMany()。这两个动作在开发期几乎每次改完 Schema 都要跑我自己的习惯是给 package.json 加一个脚本db:sync: prisma migrate dev prisma generate避免敲错。种子数据也是需要认真对待的。t3code 没有直接用一堆手工数据而是在prisma/seed.ts里写了脚本把管理员账号、几个测试用户、一批示例笔记一键灌进去。这样任何一个人拉下仓库跑完 seed 就能得到一个可以直接测试的完整环境而不是对着空数据库发呆。Prisma 的 seed 配置在package.json里声明执行命令即可prisma: { seed: tsx prisma/seed.ts }3.3 外键、索引和常见建模坑建模阶段最容易犯的错有三个。第一个是忘记考虑删除行为比如删除用户时他名下的笔记、收藏、登录 session 怎么办。t3code 里我用了onDelete: Cascade让删除用户时把关联数据一并清理但如果你做的是金融、订单类项目Cascade 要非常谨慎该软删就软删。第二个是忽略索引前期数据量小感觉不出问题等笔记表涨到几万条按作者查、按标签查都会变慢。对authorId这类高频过滤字段直接加上索引index([authorId])第三个坑是在同一分支上多人同时改 Schemamigration 文件产生冲突。我的处理方式是约定一个人主导 Schema 变更其他人拉主分支后跑prisma migrate dev做同步不要在多人并行改同一个模型。这个经验看起来很基础但在小团队项目里节省过不少脑细胞。4. 接口层设计tRPC 路由的拆分、鉴权和错误处理4.1 procedure 的三种形态public、protected、admint3code 的 tRPC 路由是跟着业务拆的有userRouter、noteRouter、tagRouter。路由里最核心的概念是 procedure也就是一条接口。create-t3-app 生成的基础目录里已经给了publicProcedure和protectedProcedure两种形态。我在src/server/api/trpc.ts里把 protected 改成这样export const protectedProcedure t.procedure.use(({ ctx, next }) { if (!ctx.session?.user) { throw new TRPCError({ code: UNAUTHORIZED }); } return next({ ctx: { ...ctx, session: { ...ctx.session, user: ctx.session.user }, }, }); });原理很简单tRPC 的 middleware 在真正执行业务逻辑之前先检查 session没有登录用户就抛异常。这样 noteRouter 里的所有查询都直接用protectedProcedure接口本身的鉴权逻辑就自动覆盖了不用每写一个接口都重复判断登录状态。我后来还加了一个adminProcedure在 protected 的基础上再判断用户的 role 是不是 ADMIN用来保护全站笔记列表。4.2 路由的按需拆分与输入校验接口参数校验我用了 zod这也是 tRPC 的默认搭配。以新建笔记为例export const noteRouter createTRPCRouter({ create: protectedProcedure .input( z.object({ title: z.string().min(1, 标题不能为空).max(100), content: z.string(), tags: z.array(z.string()).default([]), }) ) .mutation(async ({ ctx, input }) { return ctx.prisma.note.create({ data: { title: input.title, content: input.content, authorId: ctx.session.user.id, tags: { connectOrCreate: input.tags.map((name) ({ where: { name }, create: { name }, })), }, }, }); }), });这里有两个值得注意的细节。第一zod 的 schema 放在.input()里tRPC 会自动在请求进来时完成校验非法参数直接返回错误不需要你在业务代码里再写 if 判断。第二connectOrCreate这个 API 对标签这类“能枚举的关联对象”特别好用如果标签已存在就关联不存在就先创建。创建笔记这个接口从数据库操作到参数校验写在同一个函数里前后端类型自动同步这就是整套方案最舒服的地方。4.3 tRPC 错误提示的处理套路开发初期我犯过忽略错误格式化的毛病。默认情况下tRPC 把错误信息堆在一个大对象里前端拿不到干净的 message。后来我在src/server/api/trpc.ts里加了 errorFormatter把标准化错误消息抽出来export const createTRPCContext async (opts) { return { db: prisma, session: await getServerAuthSession(), ...opts }; }; const t initTRPC.contexttypeof createTRPCContext().create({ errorFormatter: ({ shape, error }) ({ ...shape, message: error.message, }), });这样前端只需要 catch 住 error再读取error.message就可以展示给用户。不要小看这一步如果项目里有几十个接口统一的错误格式能帮你少写很多重复的解析代码。前端调用时再配合 isError 状态弹提示、置灰按钮、回滚表单都能做得干净。5. 认证接入NextAuth.js Prisma Adapter 的完整链路5.1 NextAuth 配置与 Session 策略t3code 需要自建账号体系所以认证方案直接用 NextAuth.js。create-t3-app 初始化之后会生成一个src/server/auth.ts里面已经配好了 Prisma Adapter。因为我是内部小工具场景没接第三方 OAuth就自己搭了 credentials 登录很麻烦所以初期先接的是 GitHub Provider按钮一键授权。export const authOptions: NextAuthOptions { session: { strategy: jwt }, adapter: PrismaAdapter(prisma), providers: [ GitHubProvider({ clientId: process.env.GITHUB_CLIENT_ID ?? , clientSecret: process.env.GITHUB_CLIENT_SECRET ?? , }), ], callbacks: { session: ({ session, user }) ({ ...session, user: { ...session.user, id: user.id }, }), }, };这里有个关键抉择session 策略选 JWT 还是 database session。我一开始选了 database session结果发现每次请求都要查库而且需要同步维护Session模型。后来切成 JWT由 NextAuth 帮你在 token 里存用户标识不需要反复查库适配器依然负责首次登录时创建 User 和 Account 记录。对 t3code 这种内部工具来说JWT 策略完全是够用的。5.2 回调里把用户塞进 Context认证配置完成后最重要的一步是把 session 和数据库实例塞进 tRPC context。我们的createTRPCContext每次请求都会调用getServerAuthSession()拿到当前登录的用户。因为 NextAuth session 是挂在请求上的而 tRPC 默认会在请求入口创建一层 context所以这个链路是天然能对齐的。实践中的一个体会是session.user在 JWT 策略下并不总是完整包含所有用户字段特别是自定义字段如role。如果你需要从数据库里拿完整用户信息可以在 protectedProcedure 里再查一次prisma.user.findUnique。t3code 后来加管理员功能时就是这么处理的确保每次请求拿到的都是数据库里的最新角色状态而不是 token 里可能已过期的快照。5.3 我遇到过的登录回跳问题NextAuth 踩坑最多的不是配置而是一些“回跳”类问题。比如用户在私有页面触发未登录被重定向到 /api/auth/signin登录成功后又跳回原始页面——这个逻辑如果NEXTAUTH_URL配错会出现登录后跳到 localhost 或跳到无效地址。尤其是上线后域名变了忘了改NEXTAUTH_URL或者没在环境变量里同步更新用户报告最多的问题就是“登录不进去”。我的排查顺序是先看浏览器里最终落在哪个 URL再看 NEXTAUTH_URL 和生产环境是否一致90% 的问题出在这。另外部署在反向代理后面时需要确认代理传了Host头和X-Forwarded-Proto否则 NextAuth 无法判断当前是 http 还是 https回调会莫名其妙变成 http 跳转。6. 前端实现React Query 封装与 Tailwind 的样式落地6.1 把 tRPC 的 query / mutation 封装成可复用的 hookscreate-t3-app 在src/trpc/react.tsx里已经帮你把 tRPC 客户端和 React Query 融合好了。前端调用后端接口不需要自己建 service 层直接在组件里写api.note.list.useQuery()就行。t3code 的列表页是这样用的import { api } from ~/trpc/react; function NoteList() { const { data, isLoading } api.note.list.useQuery(); if (isLoading) return div加载中.../div; return ( ul {data?.map((note) ( li key{note.id}{note.title}/li ))} /ul ); }如果只是这点封装还不够mutation 之后的数据刷新才是关键。React Query 的核心是缓存失效机制创建笔记后列表必须更删不然页面数据是旧的const utils api.useUtils(); const createNote api.note.create.useMutation({ onSuccess: () { utils.note.list.invalidate(); }, });我批注一下这里的习惯invalidate()会标记列表缓存为失效React Query 自动重新拉取。很多第一次用的人会手动再调用一次useQuery拿到的 refetch效果差不多但远不如 invalidate 干净。整个前端几乎不再有手工控制 loading/error 状态的代码都是 hooks 内部状态自动处理这对减少重复代码帮助非常大。6.2 客户端组件与服务端组件的职责边界t3code 使用的是 App Router所以组件分服务端组件和客户端组件。一个典型场景页面框架、头部导航、SEO 相关部分用服务端组件笔记编辑器、按钮点击、React Query hooks 这些必须有浏览器行为的组件文件顶部必须写use client。我在这个环节犯过的错是把一个需要用户点击的按钮写在服务端组件里event handler 怎么绑都不生效后来才意识到 App Router 的边界不是由“看起来像页面”决定的而是由“需不需要交互”决定的。对应到工程上我会把页面路由保持成服务端组件只负责取数和布局再把需要交互的部分拆成独立的客户端组件放进去。这样 tRPC 的 query hooks、React 的 useState、onClick 全都集中在客户端组件里逻辑不会四处乱窜。6.3 Tailwind 布局中容易忽略的响应式细节样式部分 t3code 用的 Tailwind CSS它在体验上很像“直接给 HTML 写内联样式”但有个心智模型要转过来不是所有样式都适合用空间断点硬堆。内部工具的主要使用场景是桌面浏览器所以我没有做太多移动端适配只在具体页面加了 min-width 和 overflow-x auto避免小屏下表格把布局撑破。另一个经验是使用dark:主题变量时要提前定义好 CSS 变量而不是每个组件里分别写死颜色否则后续换主题会改到怀疑人生。我建议从项目开始就约定好bg-background、text-foreground这类语义化 class而不是直接写bg-white。7. 部署与上线Vercel 之外的自托管方案和环境检查7.1 上线前必须检查的检查清单t3code 从本地跑通到正式上线中间踩了不少环境层面的问题这里列一个我自己的检查清单DATABASE_URL必须指向生产库不能用本地库地址否则 Vercel 的 serverless 函数只会保留短暂生命周期连不上本地 socket。NEXTAUTH_SECRET换成固定随机值并且加入环境变量否则重启后 session 全部失效。在本地跑一遍next build确保构建阶段没有未捕获的类型错误和环境变量缺失。数据库迁移已经全部同步到生产库上线前跑一次prisma migrate deploy而不是migrate dev。确认生产环境数据库用户有权限执行 migration而不是只有只读权限。这些看起来都是小事但每一条我都真实踩过。尤其是最后一类权限问题生产环境 DBA 权限控制严格时最容易踩本地完全正常上线却报P1017或者 permission denied一查就是迁移脚本把旧表删不掉。7.2 自托管时的反向代理与 HTTPSt3code 的最终部署方式不是 Vercel而是团队自己一台云服务器。原因是内部工具要访问内网资源放在公网平台反而别扭。自托管最基础的反向代理我用的是 Nginx配置很常规server { listen 443 ssl; server_name t3code.internal.example.com; ssl_certificate /etc/nginx/certs/t3code.crt; ssl_certificate_key /etc/nginx/certs/t3code.key; location / { proxy_pass http://127.0.0.1:3000; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-Proto $scheme; } }注意几个容易忽略的点。首先是proxy_set_header Host $host不设置的话 Next.js 会按默认 localhost 处理请求。其次是X-Forwarded-Proto不传的话 NextAuth 分不清当前是 HTTPS 还是 HTTP登录回调会出问题。还有一点生产环境建议用next start跑编译后的产物而不是next dev后者性能和稳定性都不适合对外。7.3 生产环境下的常见问题排查部署完并不代表结束t3code 上线头几天我处理过两个挺有代表性的问题。第一个是首屏加载慢查了才发现是没开用于生产环境的构建优化本地和线上行为不一致后来重新跑next build并用next start启动首屏明显改善。第二个问题是连接池耗尽数据库在 Postgres 里默认连接数有限多个 serverless 或长驻进程同时连会把连接吃完。长时间运行的 Node 服务要显式控制 Prisma 连接池大小可以在连接串加参数或者用 Prisma Client 的connection_limit配置别让每个进程都无限制拿连接。我这几天的直接体会是上线清单里每一条背后都对应过一次实际的故障。与其等用户报 bug 再去复盘不如第一次部署前就按这个流程自检一遍。t3code 项目本身还有很多可以继续扩展的余地比如给笔记加全文搜索、做版本历史、把管理后台做得更完整但核心链路已经稳定跑了一个多月。对我来说它最大的价值不是用了多少热门技术而是从数据模型到接口再到前端的每一步都能清楚地解释出为什么这么做这本身比任何技术栈本身都重要。
t3code。单看这个名字你可能会以为是我给哪个开源工具随手起的代号。实际上它是我最近一个全栈 Web 项目的工作标题含义很直接用 T3 Stack 写出来的代码。T3 Stack 在圈子里已经不算新鲜了核心是 TypeScript、Tailwind CSS、tRPC 这三样再配上 Next.js、Prisma、NextAuth.js组成一套前后端通吃的方案。这篇文章就把我从初始化 t3code 到部署上线的完整过程做个记录包括我为什么这样选型、哪一步最容易踩坑、以及最终工程长什么样。如果你正在研究全栈开发或者想从传统的 REST API 前端脚手架切换到端到端类型安全的方案这篇应该能给你一些实际参考。1. 为什么把项目代号定为 t3codeT3 Stack 组合背后的逻辑1.1 T3 不是在凑字母而是一套可落地的全栈框架T3 Stack 的定位是“追求简单、模块化和全栈类型安全的 Web 开发方式”名字拆开就是 TypeScript、Tailwind CSS、tRPC 三样。围绕这条主线create-t3-app 默认又帮你把 Next.js、Prisma、NextAuth.js 一起接进来。第一次接触的人很容易被吓到以为要把六七个框架同时学会才能动手。但实际上这套组合的核心思路是让每一层都共享同一种“类型”语言Prisma 生成的数据库类型、tRPC 的输入输出类型、前端 React Query 拿到的数据形状全部由编译器盯着。前端调用一个接口返回字段不对编辑器当场标红根本不用跑到浏览器里看控制台。我选择 t3code 的核心场景是做一个面向小团队的内部知识库工具功能包含用户登录、笔记管理、标签分类和收藏。这类应用有很强的 CRUD 特征数据模型清晰前后端交互频繁恰恰是 T3 Stack 最舒服的地带。如果换成内容展示型站点或对 SEO 要求极高服务端渲染和静态生成权重要更大T3 的收益反而不明显。所以第一个原则是先看清自己的项目类型再决定要不要上这套组合别因为它热门就无脑跟。1.2 端到端类型安全为什么值得付出一遍学习成本传统的开发方式是后端写 REST 接口、前端根据接口文档手动定义类型。接口一多文档先跟不上类型再跟不上联调时发现问题只能靠肉眼盯。我在 t3code 里最直观的感受是接口层被 tRPC“抹平”了函数名就是从浏览器直接调用的函数名参数和返回值类型在前后端之间自动推导。改一个 Prisma 字段Schema 变了tRPC 的返回类型跟着变前端页面里用到这个字段的地方全部标红。早期这种全链路联动让我不太适应因为以前总习惯“前端先不管后端返回什么算什么”现在被迫把数据形状想清楚再动手。但是这种约束在项目中期会变成一种很强的保护。t3code 的知识库模型后来大概迭代了三轮笔记加了发布状态、标签改成多对多关系、用户加了收藏表都是先在 Schema 层改然后顺着 TypeScript 的报错一路清过去。比起以前那种“接口改了没人知道线上运行时才发现字段 undefined”的体验这点学习成本我觉得相当值。当然代价也很明确你必须在项目里保持 TypeScript 的纯度不能出现 anystring 或 any 泄漏否则类型安全链条会在某个环节断掉。1.3 t3code 项目要解决的真实场景t3code 不是一个纯玩具项目它要解决的具体问题是团队成员散落多地内部资料分散在聊天记录、共享网盘、本地文档里没人能快速找到一份旧方案的原稿。所以我给它的定位是带账号体系的轻量知识库核心路径是用户登录 → 查看自己的笔记列表 → 新建/编辑笔记 → 给笔记打标签 → 按标签检索。权限上普通用户只能管理自己的笔记管理员可以查看全站笔记列表。这个范围不大不小刚好能把 T3 Stack 里 Prisma、tRPC、NextAuth 这几个核心模块都充分用起来又不会让工程量膨胀到后期没法收拾。如果你正打算用这套技术栈做自己的项目我建议也别一上来就追求大而全先把一条用户主链路走通比塞进十个无关功能要重要得多。2. 初始化 t3codecreate-t3-app 的选项与初始化后的骨架2.1 创建项目命令与交互选项初始化用的是官方脚手架一条命令pnpm create t3-applatest t3code执行之后会进入交互式问答这里面的每一个选项都值得认真读一遍而不是一路回车。我记得实际会依次问到是否使用 Tailwind CSS、tRPC、Prisma、NextAuth.js以及选择 App Router 还是 Pages Router。create-t3-app 的哲学是“按需添加复杂度”所以它只把自己擅长的组合当成默认不强制你一次性全上。我当时的勾选结果是Tailwind CSS 开、tRPC 开、Prisma 开、NextAuth.js 开Router 选 App Router。理由很简单t3code 需要数据库、需要接口、需要登录这四个模块没有一个是多余的。Cli 还会问 Import alias默认是~/*这个保持默认就好。选完之后它会自动安装依赖并初始化 Git 仓库整个过程大概几分钟依赖装完直接用。2.2 生成出来的目录结构每一层分别承担什么初始化完成的目录结构大致是这样的t3code/ ├── prisma/ │ └── schema.prisma ├── public/ ├── src/ │ ├── app/ │ ├── components/ │ ├── server/ │ ├── trpc/ │ └── styles/ ├── .env └── package.json这个结构很容易理解我拆开说prisma/schema.prisma是数据库模型的唯一事实来源后面所有表结构都从这改src/server放服务端相关的 Prisma 实例、NextAuth 配置、tRPC context 这些“后台逻辑”src/trpc里是 tRPC 服务端路由的根定义和前端 react hooks 的封装入口src/app是 App Router 下的页面和接口路由。我第一次看到这个结构时觉得也没什么特别但实际用下来发现它的好处是边界很清楚——服务端的东西全在server里前端调用统一走src/trpc/react不会出现那种页面文件里到处散落数据库操作的写法。2.3 环境变量的准备先弄干净再动手初始化完成后第一步永远不是跑 dev server而是配环境变量。create-t3-app 会生成一个.env.example里面列出了所有需要的变量你需要复制一份到.env然后逐个填。t3code 当时至少需要这几个DATABASE_URLpostgresql://user:passwordlocalhost:5432/t3code NEXTAUTH_SECRET随意生成一段足够长的随机字符串 NEXTAUTH_URLhttp://localhost:3000数据库我用的是 PostgreSQL也可以用 SQLite但如果准备部署生产环境我建议直接从 PostgreSQL 开始避免后面换库时被一些类型的差异拖累。NEXTAUTH_SECRET可以用openssl rand -base64 32生成。这里最容易踩的坑是把.env当成代码的一部分传进仓库我在自己项目里吃过一次亏后来直接在.gitignore里把.env加死把.env.example作为唯一模板提交上去这样队友克隆下来也知道要配哪些变量。3. 数据层设计Prisma Schema、迁移和种子数据3.1 从业务模型到 Schema 的实际转换t3code 的知识库模型在 Schema 层是这样设计的用户 User、笔记 Note、标签 Tag以及用户和笔记之间的收藏关系。一个用户可以有多个笔记一个笔记可以被多个用户收藏笔记和标签是多对多关系。Prisma 里多对多通常用隐式关系写两个模型各声明一个互相指向的数组字段就行model User { id String id default(cuid()) name String? email String? unique emailVerified DateTime? image String? accounts Account[] sessions Session[] notes Note[] favorites Favorite[] } model Note { id String id default(cuid()) title String content String published Boolean default(false) createdAt DateTime default(now()) updatedAt DateTime updatedAt authorId String author User relation(fields: [authorId], references: [id], onDelete: Cascade) favorites Favorite[] tags Tag[] } model Tag { id String id default(cuid()) name String unique notes Note[] } model Favorite { userId String user User relation(fields: [userId], references: [id], onDelete: Cascade) noteId String note Note relation(fields: [noteId], references: [id], onDelete: Cascade) id([userId, noteId]) }这里我特意把 Favorite 设计成显式中间表而不是在 User 和 Note 之间直接写多对多数组。原因是显式表以后可以继续扩展字段比如加一个createdAt记录收藏时机后面要做“最近收藏排序”就很容易。Prisma 的隐式多对多关系虽然写起来省事但想加字段的时候要回头改成显式表属于前期偷懒后期还债的典型。3.2 迁移、Generate 和 Seed 的配合方式Schema 写完下一步是同步到数据库npx prisma migrate dev --name init npx prisma generate第一条命令会在数据库里建表同时生成 migration 文件第二条命令生成 TypeScript 客户端让你能在代码里直接prisma.note.findMany()。这两个动作在开发期几乎每次改完 Schema 都要跑我自己的习惯是给 package.json 加一个脚本db:sync: prisma migrate dev prisma generate避免敲错。种子数据也是需要认真对待的。t3code 没有直接用一堆手工数据而是在prisma/seed.ts里写了脚本把管理员账号、几个测试用户、一批示例笔记一键灌进去。这样任何一个人拉下仓库跑完 seed 就能得到一个可以直接测试的完整环境而不是对着空数据库发呆。Prisma 的 seed 配置在package.json里声明执行命令即可prisma: { seed: tsx prisma/seed.ts }3.3 外键、索引和常见建模坑建模阶段最容易犯的错有三个。第一个是忘记考虑删除行为比如删除用户时他名下的笔记、收藏、登录 session 怎么办。t3code 里我用了onDelete: Cascade让删除用户时把关联数据一并清理但如果你做的是金融、订单类项目Cascade 要非常谨慎该软删就软删。第二个是忽略索引前期数据量小感觉不出问题等笔记表涨到几万条按作者查、按标签查都会变慢。对authorId这类高频过滤字段直接加上索引index([authorId])第三个坑是在同一分支上多人同时改 Schemamigration 文件产生冲突。我的处理方式是约定一个人主导 Schema 变更其他人拉主分支后跑prisma migrate dev做同步不要在多人并行改同一个模型。这个经验看起来很基础但在小团队项目里节省过不少脑细胞。4. 接口层设计tRPC 路由的拆分、鉴权和错误处理4.1 procedure 的三种形态public、protected、admint3code 的 tRPC 路由是跟着业务拆的有userRouter、noteRouter、tagRouter。路由里最核心的概念是 procedure也就是一条接口。create-t3-app 生成的基础目录里已经给了publicProcedure和protectedProcedure两种形态。我在src/server/api/trpc.ts里把 protected 改成这样export const protectedProcedure t.procedure.use(({ ctx, next }) { if (!ctx.session?.user) { throw new TRPCError({ code: UNAUTHORIZED }); } return next({ ctx: { ...ctx, session: { ...ctx.session, user: ctx.session.user }, }, }); });原理很简单tRPC 的 middleware 在真正执行业务逻辑之前先检查 session没有登录用户就抛异常。这样 noteRouter 里的所有查询都直接用protectedProcedure接口本身的鉴权逻辑就自动覆盖了不用每写一个接口都重复判断登录状态。我后来还加了一个adminProcedure在 protected 的基础上再判断用户的 role 是不是 ADMIN用来保护全站笔记列表。4.2 路由的按需拆分与输入校验接口参数校验我用了 zod这也是 tRPC 的默认搭配。以新建笔记为例export const noteRouter createTRPCRouter({ create: protectedProcedure .input( z.object({ title: z.string().min(1, 标题不能为空).max(100), content: z.string(), tags: z.array(z.string()).default([]), }) ) .mutation(async ({ ctx, input }) { return ctx.prisma.note.create({ data: { title: input.title, content: input.content, authorId: ctx.session.user.id, tags: { connectOrCreate: input.tags.map((name) ({ where: { name }, create: { name }, })), }, }, }); }), });这里有两个值得注意的细节。第一zod 的 schema 放在.input()里tRPC 会自动在请求进来时完成校验非法参数直接返回错误不需要你在业务代码里再写 if 判断。第二connectOrCreate这个 API 对标签这类“能枚举的关联对象”特别好用如果标签已存在就关联不存在就先创建。创建笔记这个接口从数据库操作到参数校验写在同一个函数里前后端类型自动同步这就是整套方案最舒服的地方。4.3 tRPC 错误提示的处理套路开发初期我犯过忽略错误格式化的毛病。默认情况下tRPC 把错误信息堆在一个大对象里前端拿不到干净的 message。后来我在src/server/api/trpc.ts里加了 errorFormatter把标准化错误消息抽出来export const createTRPCContext async (opts) { return { db: prisma, session: await getServerAuthSession(), ...opts }; }; const t initTRPC.contexttypeof createTRPCContext().create({ errorFormatter: ({ shape, error }) ({ ...shape, message: error.message, }), });这样前端只需要 catch 住 error再读取error.message就可以展示给用户。不要小看这一步如果项目里有几十个接口统一的错误格式能帮你少写很多重复的解析代码。前端调用时再配合 isError 状态弹提示、置灰按钮、回滚表单都能做得干净。5. 认证接入NextAuth.js Prisma Adapter 的完整链路5.1 NextAuth 配置与 Session 策略t3code 需要自建账号体系所以认证方案直接用 NextAuth.js。create-t3-app 初始化之后会生成一个src/server/auth.ts里面已经配好了 Prisma Adapter。因为我是内部小工具场景没接第三方 OAuth就自己搭了 credentials 登录很麻烦所以初期先接的是 GitHub Provider按钮一键授权。export const authOptions: NextAuthOptions { session: { strategy: jwt }, adapter: PrismaAdapter(prisma), providers: [ GitHubProvider({ clientId: process.env.GITHUB_CLIENT_ID ?? , clientSecret: process.env.GITHUB_CLIENT_SECRET ?? , }), ], callbacks: { session: ({ session, user }) ({ ...session, user: { ...session.user, id: user.id }, }), }, };这里有个关键抉择session 策略选 JWT 还是 database session。我一开始选了 database session结果发现每次请求都要查库而且需要同步维护Session模型。后来切成 JWT由 NextAuth 帮你在 token 里存用户标识不需要反复查库适配器依然负责首次登录时创建 User 和 Account 记录。对 t3code 这种内部工具来说JWT 策略完全是够用的。5.2 回调里把用户塞进 Context认证配置完成后最重要的一步是把 session 和数据库实例塞进 tRPC context。我们的createTRPCContext每次请求都会调用getServerAuthSession()拿到当前登录的用户。因为 NextAuth session 是挂在请求上的而 tRPC 默认会在请求入口创建一层 context所以这个链路是天然能对齐的。实践中的一个体会是session.user在 JWT 策略下并不总是完整包含所有用户字段特别是自定义字段如role。如果你需要从数据库里拿完整用户信息可以在 protectedProcedure 里再查一次prisma.user.findUnique。t3code 后来加管理员功能时就是这么处理的确保每次请求拿到的都是数据库里的最新角色状态而不是 token 里可能已过期的快照。5.3 我遇到过的登录回跳问题NextAuth 踩坑最多的不是配置而是一些“回跳”类问题。比如用户在私有页面触发未登录被重定向到 /api/auth/signin登录成功后又跳回原始页面——这个逻辑如果NEXTAUTH_URL配错会出现登录后跳到 localhost 或跳到无效地址。尤其是上线后域名变了忘了改NEXTAUTH_URL或者没在环境变量里同步更新用户报告最多的问题就是“登录不进去”。我的排查顺序是先看浏览器里最终落在哪个 URL再看 NEXTAUTH_URL 和生产环境是否一致90% 的问题出在这。另外部署在反向代理后面时需要确认代理传了Host头和X-Forwarded-Proto否则 NextAuth 无法判断当前是 http 还是 https回调会莫名其妙变成 http 跳转。6. 前端实现React Query 封装与 Tailwind 的样式落地6.1 把 tRPC 的 query / mutation 封装成可复用的 hookscreate-t3-app 在src/trpc/react.tsx里已经帮你把 tRPC 客户端和 React Query 融合好了。前端调用后端接口不需要自己建 service 层直接在组件里写api.note.list.useQuery()就行。t3code 的列表页是这样用的import { api } from ~/trpc/react; function NoteList() { const { data, isLoading } api.note.list.useQuery(); if (isLoading) return div加载中.../div; return ( ul {data?.map((note) ( li key{note.id}{note.title}/li ))} /ul ); }如果只是这点封装还不够mutation 之后的数据刷新才是关键。React Query 的核心是缓存失效机制创建笔记后列表必须更删不然页面数据是旧的const utils api.useUtils(); const createNote api.note.create.useMutation({ onSuccess: () { utils.note.list.invalidate(); }, });我批注一下这里的习惯invalidate()会标记列表缓存为失效React Query 自动重新拉取。很多第一次用的人会手动再调用一次useQuery拿到的 refetch效果差不多但远不如 invalidate 干净。整个前端几乎不再有手工控制 loading/error 状态的代码都是 hooks 内部状态自动处理这对减少重复代码帮助非常大。6.2 客户端组件与服务端组件的职责边界t3code 使用的是 App Router所以组件分服务端组件和客户端组件。一个典型场景页面框架、头部导航、SEO 相关部分用服务端组件笔记编辑器、按钮点击、React Query hooks 这些必须有浏览器行为的组件文件顶部必须写use client。我在这个环节犯过的错是把一个需要用户点击的按钮写在服务端组件里event handler 怎么绑都不生效后来才意识到 App Router 的边界不是由“看起来像页面”决定的而是由“需不需要交互”决定的。对应到工程上我会把页面路由保持成服务端组件只负责取数和布局再把需要交互的部分拆成独立的客户端组件放进去。这样 tRPC 的 query hooks、React 的 useState、onClick 全都集中在客户端组件里逻辑不会四处乱窜。6.3 Tailwind 布局中容易忽略的响应式细节样式部分 t3code 用的 Tailwind CSS它在体验上很像“直接给 HTML 写内联样式”但有个心智模型要转过来不是所有样式都适合用空间断点硬堆。内部工具的主要使用场景是桌面浏览器所以我没有做太多移动端适配只在具体页面加了 min-width 和 overflow-x auto避免小屏下表格把布局撑破。另一个经验是使用dark:主题变量时要提前定义好 CSS 变量而不是每个组件里分别写死颜色否则后续换主题会改到怀疑人生。我建议从项目开始就约定好bg-background、text-foreground这类语义化 class而不是直接写bg-white。7. 部署与上线Vercel 之外的自托管方案和环境检查7.1 上线前必须检查的检查清单t3code 从本地跑通到正式上线中间踩了不少环境层面的问题这里列一个我自己的检查清单DATABASE_URL必须指向生产库不能用本地库地址否则 Vercel 的 serverless 函数只会保留短暂生命周期连不上本地 socket。NEXTAUTH_SECRET换成固定随机值并且加入环境变量否则重启后 session 全部失效。在本地跑一遍next build确保构建阶段没有未捕获的类型错误和环境变量缺失。数据库迁移已经全部同步到生产库上线前跑一次prisma migrate deploy而不是migrate dev。确认生产环境数据库用户有权限执行 migration而不是只有只读权限。这些看起来都是小事但每一条我都真实踩过。尤其是最后一类权限问题生产环境 DBA 权限控制严格时最容易踩本地完全正常上线却报P1017或者 permission denied一查就是迁移脚本把旧表删不掉。7.2 自托管时的反向代理与 HTTPSt3code 的最终部署方式不是 Vercel而是团队自己一台云服务器。原因是内部工具要访问内网资源放在公网平台反而别扭。自托管最基础的反向代理我用的是 Nginx配置很常规server { listen 443 ssl; server_name t3code.internal.example.com; ssl_certificate /etc/nginx/certs/t3code.crt; ssl_certificate_key /etc/nginx/certs/t3code.key; location / { proxy_pass http://127.0.0.1:3000; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-Proto $scheme; } }注意几个容易忽略的点。首先是proxy_set_header Host $host不设置的话 Next.js 会按默认 localhost 处理请求。其次是X-Forwarded-Proto不传的话 NextAuth 分不清当前是 HTTPS 还是 HTTP登录回调会出问题。还有一点生产环境建议用next start跑编译后的产物而不是next dev后者性能和稳定性都不适合对外。7.3 生产环境下的常见问题排查部署完并不代表结束t3code 上线头几天我处理过两个挺有代表性的问题。第一个是首屏加载慢查了才发现是没开用于生产环境的构建优化本地和线上行为不一致后来重新跑next build并用next start启动首屏明显改善。第二个问题是连接池耗尽数据库在 Postgres 里默认连接数有限多个 serverless 或长驻进程同时连会把连接吃完。长时间运行的 Node 服务要显式控制 Prisma 连接池大小可以在连接串加参数或者用 Prisma Client 的connection_limit配置别让每个进程都无限制拿连接。我这几天的直接体会是上线清单里每一条背后都对应过一次实际的故障。与其等用户报 bug 再去复盘不如第一次部署前就按这个流程自检一遍。t3code 项目本身还有很多可以继续扩展的余地比如给笔记加全文搜索、做版本历史、把管理后台做得更完整但核心链路已经稳定跑了一个多月。对我来说它最大的价值不是用了多少热门技术而是从数据模型到接口再到前端的每一步都能清楚地解释出为什么这么做这本身比任何技术栈本身都重要。
