大家聚在一起聊全栈项目的时候经常绕不开一个问题技术栈到底怎么选。前后端分离、微服务、云原生听着都挺高大上可真要一个人从零搭一个能上线、能维护、类型还安全的产品很多方案都给人一种“杀鸡用牛刀”的别扭感。我手上这个代号叫t3code的项目就是从这种纠结里长出来的。t3code说白了是一个基于 T3 Stack 的开发者工具类项目定位是“给团队内部用的代码片段管理与复用平台”。核心解决的是这么几个痛点代码片段散落在各个仓库和聊天记录里、新成员上手时找不到可复用的模板、以及常见逻辑在不同项目里反复复制粘贴却没人维护。我选择用 T3 这套全栈 TypeScript 方案来做也正是看中了它在“类型安全”和“开发效率”之间那种近乎偏执的平衡。这篇文章我会从项目选型、整体架构、核心实现、部署上线到排错实录把整个 t3code 从零到一的过程完整摊开来讲。无论是正打算用 T3 Stack 起步的新手还是已经上手但想看看别人怎么组织项目结构的开发者应该都能从里面找到点有用的东西。1. 项目整体设计与思路拆解1.1 先回答一个根本问题项目到底要解决什么很多技术方案之所以翻车不是技术本身不行而是压根没想清楚要解决什么问题。t3code 的核心需求我拆成了三块片段管理、组织共享、快速检索。片段管理做的是增删改查和分类打标这没什么新鲜的。组织共享才是重点团队成员可以把验证过的公共代码提交上去相当于一个内部的开源仓库。快速检索则是体验层面的要求不可能让用户像查数据库一样翻表格而是要有按标签、按语言、按内容关键字的联合搜索。这三块需求对应到技术上分别是 CRUD 接口、权限模型和全文检索。如果一开始就冲着微服务去设计每个模块配一个独立服务那这个项目光基础设施就得折腾半个月。我的判断很明确单体应用、全栈 TypeScript、在一个代码库里完成前后端。这也是 T3 Stack 最舒适的出场姿势。1.2 T3 Stack 的选型逻辑为什么要选这套组合T3 Stack 是一个比较新的概念核心组合是Next.js TypeScript Tailwind CSS tRPC再加上 Prisma 和 NextAuth.js 作为常用搭档。它推崇的不是“多而全”而是“少而精”每个成员都负责一块明确的能力。用 Next.js 是因为它同时承担了前端页面渲染和服务端 API 路由这让我不需要单独起一个 Express 或 Nest 服务。tRPC 的价值对接触过的人可能不太好理解但它最大的贡献是消除了前后端之间的类型断层——API 调用直接像调用本地函数一样不需要手动写接口文档也不需要在前端维护一份可能过期的类型定义。Prisma 则帮我把数据库表和 TypeScript 类型直接绑定在一起模式一改类型就跟着变。这套组合最让我满意的地方是写代码的时候不需要中断思维去补类型、补接口文档类型系统会在编译期把问题暴露出来而不是线上才炸。对于 t3code 这种业务逻辑不算复杂、但迭代频率极高的内部工具开发效率上的优势是压倒性的。1.3 主要技术选型清单层次技术选择承担职责前端框架Next.js 14 (App Router)页面渲染、路由、服务端组件后端 APItRPC v11类型安全的接口层替代 REST数据库PostgreSQL Prisma数据持久化、Schema 迁移认证NextAuth.js邮箱登录 OAuth样式Tailwind CSS shadcn/ui组件与样式体系部署Vercel Neon Postgres前端托管与数据库托管这套选型还有一个很现实的好处全都跑在 JavaScript/TypeScript 生态里团队招人门槛低。不需要专门的后端工程师前端同学也能通过 tRPC 和 Prisma 把后端逻辑改了。2. 项目架构与目录组织策略2.1 前后端边界tRPC 如何重塑开发流程T3 架构里最核心的一点就是前后端不分离或者说“逻辑分离、技术上不分离”。tRPC 的做法是把服务端函数定义成一个 router前端直接从这些 router 上调用“远程函数”。形式上是函数调用实际上是 HTTP 请求。使用 tRPC 之前我心里有一个隐忧请求多了之后每个接口都要手动写类型校验、错误处理会不会反而更麻烦实际用下来发现tRPC 把大部分模板代码都封装掉了。它的 call 过程自带类型推导前端写错参数、后端改了返回值IDE 里马上弹红根本不用等运行时报错。t3code 的典型数据流是这样的// 后端定义的一个 fragment 查询接口 const fragmentRouter router({ list: protectedProcedure .input( z.object({ language: z.string().optional(), tag: z.string().optional(), keyword: z.string().optional(), page: z.number().default(1), }) ) .query(async ({ ctx, input }) { return await getPaginatedFragments(ctx.db, input); }), }); // 前端调用 const { data } api.fragment.list.useQuery({ language: typescript, tag: auth, keyword: jwt, page: 1, });这段代码里有几个替我省大时间的细节。protectedProcedure是带登录校验的过程包装器未登录直接返回 401不需要在每个接口里手动写 session 判断。Zod 的input校验是声明式的参数类型由 Zod 推导出来前端调用时自动有完整的 IntelliSense。数据返回的类型也是由后端查询结果推导的前后端如果对不上编译期就能发现。2.2 项目目录别把所有东西都堆在 pages 里T3 项目容易让新手栽跟头的地方是目录结构。create-t3-app 只生成了一个最小骨架但业务代码如果不做分区几千行往components和utils里一塞很快就变成一锅粥。t3code 的目录组织我参考了社区里常见的 feature-based 分层方式src/ ├── app/ # Next.js App Router 页面 │ ├── (auth)/ # 登录、注册相关路由 │ ├── (dashboard)/ │ │ ├── fragments/ # 片段列表与详情 │ │ ├── settings/ # 用户设置 │ │ └── layout.tsx ├── components/ # 全局复用组件Button、Modal 等 │ └── ui/ # shadcn 生成的组件放这里 ├── server/ │ ├── api/ │ │ └── routers/ # tRPC 路由定义按业务域拆分 │ ├── db/ # Prisma Client 实例 │ └── auth/ # NextAuth 配置 ├── trpc/ # tRPC 客户端封装与服务端上下文 └── styles/ # 全局样式把 tRPC 的 router 放在server/api/routers而不是直接放在src/server下原因是后续如果要接其他服务比如事件队列、定时任务它们也可以依赖这些 router 而不关心 HTTP 层。页面组件只跟src/trpc的 client API 打交道外部模块根本不需要 import 服务端的细节这一层隔离带来了很舒服的依赖方向。2.3 权限模型设计三类角色怎么落地t3code 里的权限模型并不复杂只有三类角色访客、成员、管理员。但设计的时候要考虑扩展性因为未来很可能出现“团队”维度比如某个片段只有特定小组能看。我选择用 Prisma 的枚举字段管理角色enum Role { GUEST MEMBER ADMIN } model User { id String id default(cuid()) email String unique name String? role Role default(MEMBER) fragments Fragment[] createdAt DateTime default(now()) } model Fragment { id String id default(cuid()) title String content String language String tags String[] visibility Visibility default(TEAM) author User relation(fields: [authorId], references: [id]) authorId String createdAt DateTime default(now()) }visibility字段控制片段是公开、仅团队成员可见还是仅自己可见。之所以不用单独的权限表是因为这个项目的访问控制粒度比较粗——标记、查询时过滤即可不需要行列级权限上独立权限系统属于过度设计。3. 核心功能实操从初始化到上线3.1 创建项目create-t3-app 的完整流程初始化 T3 项目最简单的方式是直接跑create-t3-app。这里有个容易忽略的细节一定要在 Node.js 18 以上的环境里运行否则后续依赖安装或者 Next.js 14 的开发服务器会直接报错。pnpm create t3-applatest t3code交互式问询里会让你选择要启用的模块我实际勾选的是 NextAuth、Prisma、Tailwind、tRPC。ESLint 和 Prettier 默认选上这俩不显眼但非常重要团队协作时没有统一 lint 规则代码风格会全乱掉。项目生成之后建议先跑一遍npm run db:push npm run dev如果这时候能正常打开登录页说明基础链路已经通了。很多新手在这步被卡住常见原因是.env文件没有配置 DATABASE_URLPrisma 找不到数据库就直接抛出Environment variable not found: DATABASE_URL。3.2 数据库连接本地与线上的切换经验我开发时用的是本地 PostgreSQL部署后用 Neon 的云数据库。两个环境的 DATABASE_URL 不同这就对配置管理提出了要求。T3 项目用.env和.env.production区分环境。开发时本地数据库直接写.env里是本地库的 URL.env.production里是 Neon 的 URL。有个坑是 Next.js 14 里.env.production只对next build生效本地跑next dev时加载的是.env所以切换环境前一定要确认当前是哪个模式别把生产库地址写进了开发配置里。3.3 Prisma Schema 设计标签与搜索的实现细节t3code 里片段列表页需要展示语言、标签和创建时间所以我在 Fragment 模型上加了language、tags和createdAt三个字段。tags用的是String[]数组类型PostgreSQL 里映射为 text 数组查询标签时直接用 Prisma 的hasSome过滤器非常方便const fragments await db.fragment.findMany({ where: { tags: { hasSome: selectedTags }, language: languageFilter || undefined, }, orderBy: { createdAt: desc }, take: 20, skip: (page - 1) * 20, });对于关键字检索一开始我只做了title和content的contains模糊查询。实测下来发现在片段内容比较长的时候这种查询速度还能接受但功能上有明显的短板搜useState时搜不到用use-state写的代码。我后来给 Fragment 表加了一个searchVector字段用 PostgreSQL 的全文检索来做效果好了很多这个优化在排错章节里会详细说。3.4 tRPC Router 划分按业务域而不是按 HTTP 方法有 REST 经验的人容易犯一个思维定式把 router 按资源划分一个fragmentRouter里放createFragment、getFragment、updateFragment、deleteFragment四个方法。这种划分方式简单但业务一复杂就会膨胀。t3code 里我按领域划分authRouter负责登录用户信息、更新姓名头像fragmentRouter负责片段 CRUD、标签统计、关键词搜索userRouter负责成员管理、角色分配categoryRouter负责分类树结构每个 router 内部再按“进/出”分方法进是写入出是查询。tRPC 里 query 和 mutation 的区分用语义化的方式表达后前端useQuery和useMutation就可以精准对应数据缓存失效规则也好写。有一个示例值得展示片段删除时需要考虑“同时删除关联的评论表记录”tRPC 的 mutation 里可以放在一个事务里deleteFragment: protectedProcedure .input(z.object({ id: z.string().min(1) })) .mutation(async ({ ctx, input }) { return ctx.db.$transaction(async (tx) { await tx.comment.deleteMany({ where: { fragmentId: input.id } }); await tx.fragment.delete({ where: { id: input.id } }); return { success: true }; }); }),这段代码在面试或 code review 中都有讨论价值——事务保证了删除的一致性不会出现片段没了评论还在。3.5 前端页面与交互Tailwind shadcn/ui 的组合页面层我几乎没花时间设计直接用 shadcn/ui 生成的基础组件拼装。这个决定帮我省掉了大量打磨按钮、输入框、弹窗的时间页面观感也很稳定。列表页的关键是“能一眼看到搜索、筛选、新增三个操作”。我参考了 shadcn 的 Table 组件直接在一行里放置输入框、语言下拉框、标签选择器右侧放一个“新建片段”按钮。这个布局虽然简单但实际使用中用户上手零成本连培训都省了。写前端的时候有一个我自己踩出来的经验T3 项目里所有需要用到客户端 hooks比如 useState、useEffect的组件都要确保文件顶部加了use client指令。在 App Router 下未标注的组件默认是 Server Component一旦在服务端渲染里用到 hooks报错信息是英文的排查起来容易走弯路。3.6 认证与登录NextAuth 的踩坑与调优NextAuth 在 T3 里自带适配器登录方式我选了 GitHub OAuth 加一个邮箱密码登录的 Provider。使用 GitHub OAuth 之前需要在 GitHub 后台创建一个 OAuth App然后把 Client ID 和 Client Secret 配置到.env里。这里有一个我再三强调的点OAuth 回调地址一定要写对。本地写http://localhost:3000/api/auth/callback/github部署之后还要在环境变量里改成线上的完整地址。如果环境变量配错登录时大概率会报OAuthCallback错误但浏览器地址栏里的回调地址会泄露真实原因。NextAuth 的 session 策略默认是jwt也就是说用户信息会编码在 JWT 里而不查数据库。这在使用 tRPC 时有个潜在的坑如果用户被管理员删除了但 JWT 还没过期ctx.session.user依然会返回这个已删除的用户。t3code 的做法是在getServerSession之后通过 id 重新查一次用户表确保 session 对象里的用户始终是最新的。4. 部署上线Vercel 与数据库托管4.1 环境变量的部署配置部署时最忌讳的就是把本地.env直接拷贝到线上。t3code 用的环境变量一共就这几个但每个都必不可少DATABASE_URL # Neon Postgres 的连接串 NEXTAUTH_SECRET # 生成 session 密钥必须随机且长 NEXTAUTH_URL # 线上应用的根地址 GITHUB_CLIENT_ID GITHUB_CLIENT_SECRETNEXTAUTH_SECRET 不能用固定字符串应该用openssl rand -base64 32随机生成。这个密钥一旦泄漏任何人都可以伪造 session权限体系就形同虚设。因为 Vercel 的日志系统能打印服务端环境变量但不会打印 NEXT_PUBLIC 前缀的变量所以密钥类变量一律不要加 NEXT_PUBLIC 前缀避免暴露到浏览器端。4.2 常见部署问题构建失败与访问白屏部署过程中最容易遇到两类问题构建失败和访问白屏。构建失败最常见的原因是next build阶段调用了数据库。比如在layout.tsx里用了db.fragment.findMany()做预取但构建时 .env 里没有 DATABASE_URL或者 Neon 的连接串没通过环境变量注入就会直接构建失败。解决办法是把服务端的数据预取全部放在动态渲染的组件里或者给查询加一个export const dynamic force-dynamic明确告知 Next.js 不要在构建期执行。访问白屏则要区分是服务端渲染崩溃还是客户端 JS 报错。直接在浏览器开发者工具里看 Console 往往不够直观更好的方法是查 Vercel 的 Function Logs那里能看到服务端渲染的异常。我遇到过最隐蔽的一次白屏是 Tailwind 类名冲突导致样式错位但报错信息完全看不出来最后是逐个组件二分排查才定位到。4.3 上线后的监控与反馈项目上线后我会在 Vercel 的 Analytics 里关注两个指标接口失败率和页面渲染耗时。内部工具用的人不多单看起来数据意义不大但趋势一旦异常就说明代码改动引入了回归。还有一个隐藏监控点Prisma 的查询日志。t3code 里我打开了 query 日志模块发现有个接口的 N1 查询每次加载列表页都会额外查几十次标签表数据库压力直接翻倍。这个排查过程很有意思我在下一节详细写。5. 常见问题与排查技巧实录5.1 N1 查询tRPC 里最容易被忽视的性能陷阱列表页接口返回 50 条片段前端需要每条片段的作者名。最直接的 Prisma 写法是const fragments await db.fragment.findMany({ take: 50, include: { author: true }, });这个写法没问题但如果我一开始图省事先查出片段再用循环逐个查作者const fragments await db.fragment.findMany({ take: 50 }); for (const f of fragments) { f.author await db.user.findUnique({ where: { id: f.authorId } }); }这 50 次查询就是典型的 N1。Prisma 日志里会打出 51 条 SQL性能很差。正确做法是直接include关联表或者用select只取需要的字段。用 Prisma 有一个对新手很友好的判断方式看 Prisma Studio 或日志里列表接口的 SQL 数量是否等于“主查询 1 关联行数”。5.2 全文检索优化从 LIKE 到 Postgres 全文搜索第一个版本我用contains: keyword做模糊查询也就是 SQL 里的LIKE %keyword%。放到几千条片段后搜索响应是 1 到 3 秒体感很卡。我尝试用 PostgreSQL 的全文搜索替代流程是第一步给Fragment表加一个生成的tsvector列ALTER TABLE Fragment ADD COLUMN search_vector tsvector GENERATED ALWAYS AS ( setweight(to_tsvector(simple, coalesce(title, )), A) || setweight(to_tsvector(simple, coalesce(content, )), B) ) STORED;第二步加一个 GIN 索引CREATE INDEX fragment_search_idx ON Fragment USING GIN (search_vector);第三步Prisma schema 里手动加一条 migration把这句 SQL 写进去避免代码与数据库不一致。搜索接口改用searchVector字段做tsquery匹配响应时间从秒级降到 100ms 以内。这个优化经验特别值得复刻尤其是项目内容以文本为主时全文检索远比LIKE %x%可靠得多。5.3 tRPC 常见报错与排查思路把几个高频报错整理成一张速查表方便遇到问题直接对照。报错信息可能原因解决方式Unable to find a valid procedure前端调用的 router 路径写错检查 tRPC client 的api.xxx.yyy路径与后端 router 定义是否完全一致Unexpected token in JSON参数里有特殊字符未正确序列化检查 Zod schema 是否允许该字段类型必要时用z.string()加max限制Untyped property/ type error服务端新返回字段没同步到前端类型重新生成 tRPC 类型或在server/api/root.ts里导出新的 AppRouter 类型401 Unauthorizedsession 不合法或过期检查 NextAuth 配置、.env密钥确认getServerSession与withAuth的 scope 匹配PrismaClientInitializationError数据库连接串配置错误检查DATABASE_URL是否带上了?sslmoderequireNeon 是强制 TLS 连接的一个比较玄学的坑是tRPC 方法的返回值类型如果带有 Date 对象客户端序列化后会被转成 ISO 字符串但服务端拿到的类型依然是 Date。这会在某些严格类型检查里引起偏差。我的处理方式是统一在返回数据里把createdAt转成时间戳字符串目的一是为了减轻序列化压力二是让前端拿到一致的格式。5.4 团队协作与代码规范T3 项目怎么守住质量t3code 虽然规模不大但团队协作时代码规范不能放松。我们在项目里启用了 ESLint 的no-unnecessary-condition插件还有一个自定的react-hooks规则用来限制在 Server Component 里使用客户端 hooks。这些约束在 CI 阶段通过 lint 拦截确实减少了很多低级错误。代码提交信息我们约定用feat、fix、refactor、docs前缀可以直接对应到生成 changelog 的工具。提交信息不规范的 PR 会被 CI 拒绝这个门槛看起来冷漠但长远看是维护者的大救星。关于依赖升级我也有一套自己的节奏。T3 全家桶的版本更新比较频繁新版本带来的 bug 往往比新功能更值得警惕。我会每隔大概两周做一次pnpm update --latest升级后全局回归一遍登录、创建片段、搜索、删除四件套。这几个核心流程跑通其他细枝末节的影响不大。6. 写在最后的一些体会t3code 做到现在我最大的体会是技术选型真的不需要赶时髦关键是能不能让你的团队和项目节奏配合起来。T3 Stack 受欢迎不只是因为它用了 Next.js 和 tRPC而是它帮我把大量“心智负担”从脑内转移到了类型系统里。类型就是文档编译就是测试这两条比任何框架本身都值钱。如果你打算用 T3 做一个自己的项目我给的建议是别看太多“最佳实践”先把最小闭环跑通——一个页面、一个数据库表、一个 tRPC 接口、一次部署。跑通之后你就有了一个可以一直迭代的骨架接下来每一步都是往上添砖加瓦而不是推倒重来。最后再提一个小技巧如果拿不准 T3 的某一个模块该怎么用直接去看node_modules/t3-oss/env-nextjs的源码注释它比任何教程都更接近当下最新版的实际实现。很多“老教程”里的写法在新版本里早就变了只有源码不会骗人。