我一直有个习惯：每个新项目启动的头两天，总得跟 Next.js、TypeScript、Tailwind、tRPC、数据库这一整套装修队重新打交道。配置一遍两遍还好，十遍八遍之后，人就麻了。后来我把自己的初始模板固定下来，给它起名叫 t3code，每次开新项目直接从这个基线走，不再从零搭积木。这篇文章就把 t3code 这套东西拿出来聊聊：它解决什么问题、目录是怎么拆的、数据库和认证怎么接、哪些地方我反复改过，以及把它从“能跑”变成“真正敢用在生产环境”的过程中踩过的坑。
我默认看这篇内容的人，至少写过一段时间的 Next.js，知道 API Route、中间件、数据库 ORM 这些概念，但不想在项目脚手架上反复做重复劳动。如果你正好在寻找一套顺手、类型安全、能快速长出业务代码的全栈模板，那么 t3code 这套思路可以直接抄作业。
1. 放着成套工具不用，为什么我还要维护 t3code
1.1 每个项目的重复劳动，其实比你想的多得多
很多人起步都从官方的 create-t3-app 开始。它确实开了个好头：TypeScript、Next.js、Tailwind、tRPC、Prisma/Drizzle、NextAuth 全都码好了，初始化项目的时候问你几个问题，立刻能跑。可跑起来之后，事情才开始变麻烦。
你要做自己的鉴权流程，要决定登录后跳转到哪里，要处理数据库迁移和种子数据，要把线上数据库连接串、Cookie 域名、图片上传目录这些环境变量捋一遍。这些工作根本没写在任何 README 里，全靠自己在项目里不断调试。后端接口的命名风格、tRPC procedure 放在哪个 router、页面组件从哪里取数据，每个人习惯都不同。团队稍微大一点，A 写的接口 B 根本找不到，B 建的页面 C 又不敢动。t3code 要解决的正是这两类问题：私有化的工作区组织和统一的工程约定。
叫它模板也好，叫它脚手架也好，我更愿意把它理解成一套“启动基线”。基线里的每一行配置都是我用过的、验证过的，不是为了展示最新特性而堆上去的依赖。
1.2 t3code 和 create-t3-app 的定位区别
得说清楚，t3code 不是要替代 create-t3-app，也不是另起炉灶搞一个更花哨的生成器。create-t3-app 的价值在于“快速生成一个符合社区最佳实践的初始项目”，它面对的人群很广，所以选择也很泛。比如数据库给你 SQLite 起步，部署默认按 Vercel 的思路来，状态管理完全不管。
t3code 更像我给长期项目准备的一张固定手术台。它有明确的业务偏好：
- 数据访问层用 Drizzle ORM，而不是 Prisma；
- 服务端路由全部走 tRPC，不开放随意写混合 API；
- 认证固定用基于 NextAuth 的会话方式，不走 JWT 无状态那套；
- 共享组件和业务组件分开目录，业务组件必须能直接用 session 拿当前用户。
这些偏好不一定适合所有人，但对做中后台系统、内容社区、内部工具这类项目，它非常合适。你可以把它看成一个有主见的模板：它不问你数据库用哪个，因为我已经替你把常见决策做完了；但你随时可以在它的基础上改，毕竟是自己的仓库。
1.3 我把 t3code 收缩成三个核心价值
第一是类型安全。从数据库表到 tRPC 入参，从服务端返回值到前端页面 props，整个链路能自动推导就自动推导，不在任何一环节掉链子。第二是边界清晰。server 代码、client 组件、共享工具、迁移脚本各归其位，新成员拿到仓库不迷路。第三是可快速验证。拉下来配置好环境变量，跑一条迁移命令，再跑 dev server，立刻就有能登出登录、能查能写的 demo。
只要这三点立住了，脚手架就算称职。业务代码怎么写是你自己的事，但地基不能歪。
2. 开工前的环境决策，决定了 t3code 一半的稳定性
2.1 Node、包管理器与版本锁定的现实
这类模板最容易翻车的地方就是版本。离开了对应的 Node 环境，Next.js 跑不转，tRPC 的类型推导出现怪报错，Drizzle 的迁移行为不一致，很多时候都不是你写错了，而是版本组合有问题。
我在 t3code 里固定了这样一套运行环境：
| 依赖 | 锁定版本范围 | 说明 |
|---|---|---|
| Node.js | 20.x 或 22 LTS | 18 也能跑，但有些新 API 不齐，不建议 |
| pnpm | 9.x | 依赖安装快，node_modules 干净，配合 monorepo 顺手 |
| Next.js | 15.x | 基于 App Router，服务器组件和客户端组件边界清晰 |
| TypeScript | 5.5 以上 | strict 必须打开，noUncheckedIndexedAccess 保持开启 |
| React | 19.x | 和 Next.js 15 配套，别自己单独升级 |
| tRPC | 11.x | 把 context 和 middlewares 机制用好即可 |
这套组合看起来没什么惊奇的，但它是经过实际项目验证的稳定态。所谓稳定不是指永远不升级，而是指在你明确知道新版本会带来什么之前，不要跟着最新版本走。我吃过一次亏：React 19 RC 出来时手痒升级，结果某个第三方组件库不兼容，页面直接白屏，花半天时间排查才发现是版本冲突。从那以后，t3code 的 package.json 里所有关键依赖全部锁定版本范围，不玩模糊匹配。
2.2 数据库选型：开发环境 SQLite，生产环境 Postgres
很多全栈模板会用 Prisma，因为它封装得好，迁移体验也顺。但我在 t3code 里特意换成了 Drizzle ORM。原因很简单：Prisma 的运行时引擎太重，类型提示有时候绕一圈才能拿到关系数据；Drizzle 是轻量库，直接贴近 SQL 语法，写复杂查询时不容易被抽象束缚。尤其做报表、聚合统计这类查询，Drizzle 的自由度明显更舒服。
数据库本身我有明确策略：
- 本地开发用 SQLite，文件数据即学即用，不需要装服务；
- 生产环境用 Postgres，连接串通过环境变量注入；
- 迁移和种子数据统一走 Drizzle Kit 的命令执行。
这样做的好处是，新加入的同事不用先折腾一套本地数据库服务就能立刻跑起来。等到要部署时，把DATABASE_URL一换，跑一遍 migrate，功能几乎不用改。SQLite 和 Postgres 之间固然有一些方言差异，但 t3code 的 schema 里我会刻意避免用只在某一个数据库里支持的特殊类型，多用字符串、整数、时间戳和 JSON 这种共性字段。
2.3 环境变量的管理比想象中重要
t3code 里我专门维护了两套环境变量示例文件：一套是.env.example，一套是.env.local.example。前者放所有可公开的默认值，后者放带验证逻辑的私有配置。
有个大量项目都会犯的错：把所有配置都放进NEXT_PUBLIC_前缀。一旦你有任何东西被加了这个前缀，它就会被打包进浏览器端。数据库地址、API 密钥、签名秘钥，这些一旦进入浏览器 bundle，等于把家门钥匙挂在大门口。我处理的标准是：
- 只在客户端组件里必须读到的公开值，才用
NEXT_PUBLIC_； - 其它一切敏感值，包括数据库连接串、认证 secret、第三方服务的密钥，全部放进服务端环境变量；
- t3code 里写了一个
env.ts，用 zod 对启动时的环境变量做校验，缺了哪个直接启动报错，不会让你带着坏配置跑半天。
这个校验层刚开始觉得有点多余，但真上了生产后它救过我好几次。比如某次部署时忘了把某个服务端密钥填进去，本地一切正常，线上接口却一直报 401。后来我把配置校验前置，环境变量不对直接不让项目起来，省掉了大量摸黑排查的时间。
3. t3code 的骨架里，我刻意保留和刻意砍掉的部分
3.1 目录结构把“服务端”和“客户端”刻在名字里
我从第一次整理 t3code 起，就坚持用src/server和src/client这样的顶层目录分隔。很多人觉得反正 App Router 会自行区分 server 和 client 组件，为什么还要在目录上再分一遍？我的回答是，目录划分不只是给编译器看，更是给人看的。
真实项目里，数据库 schema、tRPC 路由、认证逻辑这些东西一旦散落各页面里，维护成本会指数上升。我也见过把 API 路由全写在app/api下面、把业务逻辑全放在组件文件里的代码库，前期跑得很美，到了第四五个迭代周期就开始痛苦，一个数据库字段改名要翻十几个文件。
t3code 的目录大概是这样的：
| 路径 | 放什么 | 关键约束 |
|---|---|---|
src/server/db | 数据库连接、schema 定义 | 不允许被客户端组件直接引用 |
src/server/auth | 认证配置、session 结构定义 | 只在服务端调用 |
src/server/api/routers | tRPC 路由，按业务模块切分 | 每个 router 只写自己领域内的 procedure |
src/server/api/root.ts | 汇总所有 router 并导出类型 | 供前端依赖推导类型 |
src/client/components | 全局共享的 UI 组件 | 纯展示，不直接调用 tRPC |
src/client/features | 业务模块组件 | 可以调用 tRPC hooks，也可以读 session |
src/trpc | tRPC client 与 server caller 封装 | 提供类型安全链路的端点 |
只要有新页面需求，先判断它属于哪个业务模块，再决定是把组件放 features 还是复用全局 components。这套约束不算复杂，但它让整个仓库看起来有一致性。新成员不需要问“这个 hook 我该放哪儿”，因为目录结构已经给了暗示。
3.2 tRPC Router 的拆分不是越细越好
在 t3code 里，我按领域拆 router，而不是按表拆 router。比如一个社区网站，我不会建usersRouter、postsRouter、commentsRouter这样的“表驱动”结构，而是建memberRouter、contentRouter、interactionRouter。为什么？因为用户发起一个请求时，往往是“登录用户查看某篇文章的评论并判断是否点赞”，它天然跨越了一张以上的表。如果 router 和数据库表一一对应，前端就得发多个请求再自己组装数据；按业务领域拆分，一个 procedure 就能聚合好再返回。
当然每个业务模块有多长就写多长，不是非得把 procedure 拆到一个文件里才算优雅。一个领域下几十个 procedure 是正常的，但如果一个 router 文件超过 300 行，我就会把子路由再往下拆一层，比如把 posts 的列表查询抽成contentRouter.listPosts、contentRouter.detail这样的语义化路径。tRPC 的嵌套路由层层最终也会被自动推导，所以前端调用不会多出负担。
这里要强调一个约定：所有返回数据都必须经过 zod 校验或手动结构化，不要把整个 Prisma/Drizzle 返回对象直接塞给前端。多余字段出现在响应里，不只会徒增流量，还可能悄悄把服务端内部信息带给浏览器。t3code 的每个 procedure 都有一条不变量：输入和输出的边界永远明确。
3.3 认证和权限做了哪几层
t3code 的认证选用基于 session 的 NextAuth（现在叫 Auth.js）。选择它而不是写死 JWT 的原因很简单：我需要支持数据库持久化会话，还要在 tRPC middleware 里直接拿到当前用户。用 JWT 当然也能做，但一旦想踢掉某个用户的会话或者让管理员封禁账号，无状态 JWT 就不好使了。
我在 t3code 里设了三层防护：
- 数据库字段层：user 表里有 role 字段，默认
user，管理员单独标记； - tRPC 中间件层：定义
protectedProcedure和adminProcedure，没登录的一律拒绝，角色不够的拒绝或返回特定错误码； - UI 层：客户端用
useSession控制按钮和入口的显示，但这只是体验优化，真正的安全判断永远在服务端完成。
还特别做了一个处理：服务端 procedure 一旦拦截到未登录请求，返回的错误类型要统一。我在 t3code 里贡献了一个自定义 tRPC error，前端统一拦截并跳到登录页，这样就不会出现有些接口返回 401、有些返回 403、前端处理逻辑东一块西一块的情况。
4. 带 t3code 跑一遍：从数据库模型到页面渲染的完整链路
4.1 先定需求，再定义数据结构
光说不练没意思。我用一个具体场景演示 t3code 的完整使用流程：做一个带登录和发帖功能的迷你社区，页面能展示所有帖子，登录用户可以发新帖，管理员能删除违规内容。
第一步是定义数据结构。在src/server/db/schema.ts里写：
import { pgTable, text, timestamp, uuid } from 'drizzle-orm/pg-core'; import { relations } from 'drizzle-orm'; export const users = pgTable('users', { id: uuid('id').defaultRandom().primaryKey(), name: text('name').notNull(), email: text('email').notNull().unique(), role: text('role', { enum: ['user', 'admin'] }).default('user').notNull(), createdAt: timestamp('created_at').defaultNow().notNull(), }); export const posts = pgTable('posts', { id: uuid('id').defaultRandom().primaryKey(), authorId: uuid('author_id').references(() => users.id).notNull(), title: text('title').notNull(), body: text('body').notNull(), createdAt: timestamp('created_at').defaultNow().notNull(), });这段代码看起来简单，但它已经包含了三个隐性的规范：所有主键都生成式defaultRandom()，不用自增数字，防止通过 ID 遍历资源；每一个字段名都显示声明，避免 Drizzle 默认命名和团队规范冲突；作者和文章之间通过外键标明关系，关系模型后期扩展评论时非常好加。
4.2 在 tRPC 里写一个创建帖子的 procedure
数据结构定义完了，接下来是服务端操作。t3code 里所有客户端请求都走 tRPC，所以我直接在 router 里加一个写操作：
import { z } from 'zod'; import { createTRPCRouter, protectedProcedure, publicProcedure } from '../trpc'; import { posts } from '../../db/schema'; import { desc } from 'drizzle-orm'; export const contentRouter = createTRPCRouter({ listPosts: publicProcedure.query(async ({ ctx }) => { return ctx.db.select().from(posts).orderBy(desc(posts.createdAt)).limit(50); }), createPost: protectedProcedure .input( z.object({ title: z.string().min(1).max(100), body: z.string().min(1).max(5000), }) ) .mutation(async ({ ctx, input }) => { const authorId = ctx.session.user.id; const [created] = await ctx.db .insert(posts) .values({ authorId, title: input.title, body: input.body }) .returning(); return created; }), });有几处细节值得展开。
publicProcedure.query用来读公开数据，protectedProcedure.mutation用来写数据。这样粗看只是命名不同，它其实把“谁可以看”和“谁可以写”从业务逻辑里抽离出来了。以后新增一个 procedure，复制模板的时候一眼就知道该套哪个中间件。
ctx.db来自 tRPC 的 context。在src/server/api/trpc.ts里，我每次请求都会创建一条全新的数据库连接实例，并读取当前 session 塞进 context。这样每个 procedure 里都能直接用ctx.session.user.id，不用再在业务逻辑里到处导入认证函数。
输入校验用 zod，既做参数检查也做类型推导。前端调用它的时候，根本不用定义“CreatePostParams”这样的接口，输入输出类型会直接从 server 端推导到浏览器端。
4.3 前端组件如何调用，Error 分支怎么处理
t3code 前端调用服务端的流程固定为三行：用api.content.listPosts.useQuery()拉数据，用api.content.createPost.useMutation()发写操作，用useSession()控制是否显示输入框。
在一个客户端组件里面，代码大概是：
'use client'; import { useSession } from 'next-auth/react'; import { api } from '~/trpc/react'; export function PostList() { const { data: session } = useSession(); const { data: posts, isLoading, error } = api.content.listPosts.useQuery(); const createPost = api.content.createPost.useMutation({ onSuccess: () => { // 这里一般会触发列表刷新或重新请求 }, }); ... }这里我想强调onSuccess的陷阱。很多新手会在 mutation 成功后手动更新本地数组，但一旦数据来源来自服务端 query，手动更新往往会导致缓存不一致。t3code 里我推荐的做法是 mutation 成功后调用utils.content.listPosts.invalidate()，把列表查询标记为过期，让 tRPC 自动重新拉取。这样页面永远展示服务端最新状态，不会出现自己拼出来的数据和数据库不一致的诡异 bug。
Error 分支同样不能省。tRPC 中间件抛出的错误会在浏览器端变成统一异常对象，我建议自定义一个全局错误组件，按error.data.code分别渲染未登录、无权限、参数错误等场景。没有这个分支，线上用户一旦遇到问题，只看到一个空页面或原始异常栈，体验非常差。
4.4 这个链路好在哪：小改动不需要跨层理解
把上面这段走通之后，t3code 的好处就很直观了。如果我只想改“帖子标题最长 100 字”这一条规则，只需要改 zod 的max(100)，前端类型会自动变成string长度为 100，连表单校验都能从中间件设计上得到提示。如果我想在列表里显示作者名字，只需要改 schema 里的关联查询，返回结构一变，前端组件也会跟着类型报错提醒你更新。
这种改动不是靠规范压出来的，而是类型系统自动推着项目经理和前端工程师往正确方向走。项目规模越大，这种“自动的纠偏能力”越值钱。
5. 这几处修改，让 t3code 从“能跑”变成“敢用”
5.1 迁移脚本和种子数据，是新同事的第一道救命绳
最开始 t3code 只有 schema 定义，没有种子数据。同事拉仓库跑起来之后，页面上空空如也，他得自己打开数据库面板手动插几行数据才能开始调试。这种事一次两次还能忍，多了绝对影响效率。后来我加入了标准化的迁移和种子操作。
做法很简单：
# 生成迁移文件 pnpm drizzle-kit generate # 应用到数据库 pnpm drizzle-kit migrate # 写入初始化数据 pnpm tsx src/server/db/seed.ts种子数据会生成一个测试账号和一个管理员账号，并预置几条帖子。跑完这套流程，页面立刻有内容可看，登录、发帖、权限验证全都能当场验证。种子数据质量我特别看重，尽量接近真实业务的形态，而不是随便 fill 几个 null 进去。因为种子数据本身就是文档，它告诉新来的同事“这套系统里会有哪些资源、字段填什么格式”，比读 README 直接很多。
5.2 App Router 带来的服务端组件与会话的拉扯
Next.js 15 的 App Router 非常喜欢把组件写成服务端组件，但 NextAuth 默认给客户端组件提供的useSession必须是 provider 包裹下的客户端组件。这两者之间就有冲突：你在 layout 里面包了SessionProvider，但服务端渲染时又拿不到客户端 context 里的 session。
t3code 的解决办法是双路并行：
- 服务端组件内部如果需要用户信息，直接调用一个封装好的
getServerAuth()，它负责在服务端返回当前 session； - 客户端组件需要响应式地监听登录状态时，才用
useSession； - 页面标题、元信息等静态内容，无论用户是否登录都一样渲染，不阻塞在认证逻辑上。
这一点建议所有准备把 NextAuth 和 App Router 一起用的人提前想清楚。如果你只依赖服务端 session，会发现登录跳转后页面不能实时刷新用户状态；如果你全页面都用客户端 session，又丢了 RSC 的性能优势。只有明确“哪里需要实时状态，哪里只需要初始信息”之后，才能各取所长。
5.3 部署环境里的三个隐蔽错误，我每个都踩过
第一，Cookie 域名的配置。本地开发时一切正常，一旦部署到正式域名，如果AUTH_URL或NEXTAUTH_URL没有改成线上地址，Cookies 不会带入后续请求，用户好不容易登录成功，一刷新又回到未登录状态。表面看是登录失效，实际是环境变量漏配。
第二，Postgres 连接串的 SSL 问题。很多托管数据库默认要求 SSL 连接，但本地的 SQLite 完全没有这个概念。第一次部署时，迁移命令会报SSL connection is required，直接把服务进程干挂。t3code 的生产配置模板里，我会在连接串里显式加上 SSL 的模式参数，并把这个坑写进部署文档。
第三，迁移脚本的执行环境。本地跑迁移没问题，但线上如果是从代码仓库直接构建部署，Docker 镜像里可能没有可执行的数据库迁移工具链，或者环境变量根本没有传进迁移容器。现在 t3code 把这个动作放进了部署流水线的启动钩子，并且单独记录迁移日志，部署失败时第一时间能看出来是代码问题还是迁移问题。
这三个错误不复杂，但它们有一个共同特点：本地永远测不出来。只有把生产环境当作一等公民来对待，模板才真正到了“敢用”的层级。
5.4 给 t3code 装上“体检机制”
把模板维护到后面，我觉得最有价值的一件事是加了一层静态检查。这里说的不是 ESLint 那种语法层面的检查，而是项目级的“体检”：比如是否存在客户端组件直接引用了src/server下的某个模块，是否存在 procedure 没有加输入校验就暴露出去，是否某个NEXT_PUBLIC_变量被错误用于服务端逻辑。
这些检查可以通过脚本跑，也可以在 CI 上执行。t3code 里我写了一个scripts/check.ts，每次跑部署流水线之前自动执行。它的思想很简单：模板提供的边界和规范，机器能查的部分不要让代码评审去靠肉眼保障。有了这套机制以后，团队里有人不小心把服务端代码 import 到客户端组件，CI 会直接标红，而不必等到构建时才报错。
6. 下一步：t3code 的边界，以及我期待的团队演变
6.1 模板再强，也顶不住“上线前随手改一行”
我见过太多优秀的脚手架最后死掉，不是因为技术过时，而是因为业务现场总有人为了赶进度做出临时改动。比如直接在某一个页面的客户端组件里写死数据库字段名，把 tRPC 的返回结果强行塞到 Form 表单而不是走验证，甚至绕过 procedure 直接 import 数据库实例。这些做法单看都没问题，但累积起来，模板的边界就形同虚设。
所以我在团队里定了一个规矩：业务代码可以随意扩展，但想改 t3code 核心目录里的文件，必须有至少两个人 review 并且说明理由。这个规矩不是为了卡流程，而是让每个人动手前想清楚，他到底是在修模板的 bug，还是在给自己的业务打补丁。打补丁的代码放进业务目录就好，别污染基线。
6.2 我对 t3code 的后续计划
接下来我会着重补两件事。
一件是把测试的框架铺得更平。目前 t3code 里只对 tRPC procedure 做了简单的单元测试，用 vitest + 内存数据库来验证。后面我计划增加更多端到端的场景测试，从登录到发帖到管理员删帖，把整条链路用自动化脚本固化下来。脚手架这种东西，一旦被信任，就不能动不动退步。
另一件是补一份“决策记录”文档。把第一次为什么选 Next.js、为什么用 Drizzle 而不是 Prisma、为什么 session 优先于 JWT，全部写进仓库里的docs/decisions目录。以后任何人不理解某个设计，不想问人，读那份记录就知道当初的权衡过程。比口口相传靠谱得多。
6.3 最后说一点维护模板多年的个人体会
说实话，t3code 这个名字起初只是我本地仓库的随手命名，后来用得习惯了，团队里也这么叫。真正的价值不在某一个目录结构或某一个现成的配置项，而在于它能帮我省出现概率最高的那些“判断题”。今天新项目用什么数据库、登录用什么方案、输入框校验放哪一层，这些决策其实早就被重复过无数次，真的有固定答案。把它们锁进模板，把思考时间留给真正有挑战的业务问题，才是我维护它的最终目的。
如果你也在维护自己的脚手架，不要急着加功能和依赖。先把项目中反复出现的样板写进模板里，把每次犯错的原因写进文档里，很多问题自然就提前被挡住了。
