企业官网建设流程全解析

t3code 这套东西，我盯了有一阵子了。你要说现在搞全栈开发，最不缺的就是技术选型，随便一搜全是 Next.js、NestJS、Nuxt、Spring Boot 加上各种 ORM 排列组合。但真等到自己搭项目脚手架的时候，反而容易卡在第一步：到底用什么组合，才能既保证类型安全、又不太折腾、还能让我这个“半后端”选手不露怯？t3code 就是在这种纠结里冒出来的一个答案，它把当前全栈 TypeScript 社区里最成熟的那套东西——T3 Stack 的核心理念，浓缩成了一个可以直接抄作业的代码模板。

先说清楚它是什么。t3code 不是某个框架的名字，它是一个基于 TypeScript 全栈技术栈的起步项目模板，核心围绕 Next.js、tRPC、Prisma、Tailwind CSS 这一整套组合展开。它解决的是“从零搭一个带数据库、带 API、带鉴权、带 UI 的全栈应用，到底需要踩多少个坑”的问题。对于想快速验证 idea、做毕设、写内部工具，或者说想系统学习现代全栈 TypeScript 开发的人来说，这套代码能帮你省掉大量查文档和调配置的时间，直接看到一个可运行的完整闭环长什么样。

我刚开始接触 t3code 的时候，其实第一反应是“又一个脚手架生成器”。但真正把它跑起来、把代码一行行读过去之后，才发现它最值钱的地方不是那几条命令，而是背后的技术取舍和代码组织方式。这篇文章我不会光是夸它好用，我会把这套模板里每个核心模块的原理、配置、实际跑起来会遇到什么问题、以及我踩过哪些坑，全部摊开来聊一遍。无论你是刚入行的前端新手，还是想转型全栈的老手，看这一篇应该能省不少弯路。

1. 内容整体设计与思路拆解

1.1 为什么偏偏是这套技术组合

聊 t3code 之前，得先理解它背后那个 T3 Stack 的选型逻辑。T3 Stack 的官方定位是“构建健壮、类型安全的全栈 Web 应用”，它选型有一个非常朴素的标准：只选那些能最大限度发挥 TypeScript 优势、同时又能减少样板代码的工具。我实际用下来的感受是，这套组合最打动我的不是单个工具多炫，而是它们之间那种“无缝咬合”的关系，很少有别的技术栈能在一开始就把类型整得这么顺。

具体来说，Next.js 负责应用框架，解决路由、SSR/SSG、API 路由这些 Web 应用最常见的骨架问题。Prisma 负责数据层，提供类型安全的 ORM，数据库表结构直接生成 TypeScript 类型，查询结果不需要再手写 interface。tRPC 负责 API 层，它跟传统 REST 或 GraphQL 最大的区别是：你在前端调用后端的函数时，类型是直接“渗透”过去的，服务端改了返回值类型，前端编译立刻报错。这一条龙下来，就从“两个系统之间靠约定传输类型”变成了“整个应用共享同一套类型宇宙”。

Tailwind CSS 在模板里的角色相对独立，但实际体验也很关键。它解决的是样式提案的问题，不需要频繁切换文件写 CSS，在组件里直接写类名，社区生态也非常成熟。t3code 把这四样组合在一起，再加上 NextAuth.js 做鉴权，就构成了我认为“最不折腾”的全栈起步方案。

1.2 这套方案的优势与代价

选这套技术栈不是没有代价的。我见过很多团队一开始冲着 tRPC 的新鲜感去，结果 API 边界划分不清楚，服务端和客户端代码揉成一团，最后维护起来比 REST 还痛苦。所以 t3code 这类模板的价值，恰恰在于它帮你提前规划好了“什么代码放在哪一层、哪些逻辑应该暴露给前端、哪些只属于服务端”。这种组织方式才是它真正值得学的地方。

我拿一个具体例子来解释这套组合不需要什么代价但依然很香的原因。假设你要做一个记账应用，传统 REST 方案里你要先在服务端定义一个/transactions路由，再写 controller、service、repository，然后前端再根据后端返回的数据类型自己维护一个 interface。来回对字段，总有对不上的一天。用 tRPC 的话，你在服务端写一个getRecentTransactions的查询函数，Prisma 返回的类型会直接推断到这个函数的返回值里，前端调用trpc.getRecentTransactions.query()时，返回的数据结构、类型、包括 null 判断的逻辑全都在 TypeScript 编译器里给你兜底。字段改名、类型调整、新增过滤参数，这些在传统方案里最容易出的问题，在这里都会被下降一个数量级。

当然，它也有明显的适用边界。首先是动态路由和 SSR 相关的复杂场景，Next.js App Router 的 Server Components 和 tRPC 的配合需要多写一些配置；其次，如果整个团队对 TypeScript 不熟，那 tRPC 的类型渗透能力反而会变成“类型地狱”。另外，这套组合的运行时性能依赖 Next.js 的部署环境，如果服务器资源比较吃紧，需要考虑冷启动和内存占用的问题。t3code 的价值不是让你觉得“什么都能干”，而是让你清楚“这套方案在哪条路上走得又快又稳”。

1.3 学这套模板的正确姿势

我见过不少朋友拿到 t3code 之后的第一反应是git clone然后npm run dev，看到页面跑起来就觉得自己会了，过两天发现还是啥也写不出来。这不是模板的问题，是学习的方式有问题。我建议拿到手之后先别急着改业务代码，先干三件事：

第一件事，把目录结构完整看一遍。搞清楚src/server和src/app的区别，搞清楚哪些文件是服务端代码、哪些是“同时存在于两端”的共享类型。第二件事，把 tRPC 的 router 定义逐行读一遍，最好自己手动写一个小 router，比如getHello，只返回一条字符串，但把 query 和 mutation 的流程跑通。第三件事，把 Prisma schema 改一次，加一张表，然后跑npx prisma migrate dev，看看类型是怎么自动生成出来并蔓延到全项目的。这三步做完，你才真正摸到了 t3code 的门道。

2. 核心细节解析与实操要点

2.1 数据层：Prisma 与数据库连接

t3code 默认带的 Prisma 版本已经进化到了很顺手的程度。它在prisma/schema.prisma里预置了一个 User 模型，还带了一个基础关联关系。我的建议是，第一次上手的人千万别把这份 schema 原封不动用在自己的项目里，因为模板里那些示例字段属于“给你演示用的”，你要做真实需求时往往需要先清掉重写。清空重写不代表推倒重来，关键是理解 Prisma 的字段类型映射规则。

这里必须提一个我踩过的坑：数据库连接串里的?schema=public参数，以及连接池配置。t3code 默认用 PostgreSQL，连接串在.env里。很多新手以为数据库跑不起来是代码写错了，其实大概率是本地 PostgreSQL 版本和 Prisma 的兼容问题，或者连接串里少了 SSL 参数。我在本地跑的时候，明明 DBeaver 能连上，Prisma 却报Can't reach database server，最后发现是 IPv6 解析的问题，必须把localhost改成127.0.0.1才行。

另一个重点：Prisma Client 的生成位置在node_modules/.prisma/client，但类型声明是映射到项目里的src/generated路径的。你每次改了 schema 之后，一定要重新跑npx prisma generate，否则前端拿到的类型还是旧的，编译器的报错信息会让你莫名其妙。t3code 的 postinstall 脚本里其实已经内置了 generate，但如果你跳过安装 npm 依赖直接跑 dev，就会遇到类型缺失的报错。

2.2 API 层：tRPC 的 Router 与上下文

t3code 里最核心的抽象就是 tRPC 的 router。它的代码组织遵循了一个清晰的原则：按领域建模，而不是按“页面”建模。也就是说，你写的是postRouter、userRouter、commentRouter，而不是homePageApi、detailPageApi。这个差别虽然不起眼，但对大型项目的可维护性影响巨大。

你在src/server/api/routers/目录下会看到每个 router 都继承了createTRPCRouter中的一个基础 timer。这个 base 里带有protectedProcedure和publicProcedure两种预设流程。我必须要提醒的一点是：t3code 的鉴权默认绑定了 NextAuth.js，也就是说你必须在调用接口前明确“这个操作是否需要用户登录”。很多人一开始没搞清楚protectedProcedure和publicProcedure的区别，把需要鉴权的接口写成了 public，结果前端绕过了权限控制直接拿到敏感数据。这个问题的严重性平时不发散不出来，一旦项目上线，它就是最致命的安全漏洞。

我在实际项目中习惯自己再加一层requireAdmin的 procedure 封装，用于后台管理接口。原理很简单：直接在 middleware 里判断ctx.session?.user.role，不是管理员就直接抛TRPCError，这样业务代码里就不再需要到处写权限判断了。这也是 t3code 这类模板最值得复制的地方——它不是把逻辑塞满在每个 handler 里，而是通过 procedure 这个抽象层把公共逻辑收敛住。

2.3 前端与 API 的类型安全闭环

t3code 在客户端侧的做法非常值得单独聊一段。传统项目里前端要调接口，你得手写一个 API 封装函数，再定义请求和响应的 interface，后端换了字段类型，前端往往还蒙在鼓里。t3code 用的是src/trpc/react.tsx里的trpcclient 对象，它直接从前端的 React Query 里把类型推断出来。

让我用人话解释一下这个模型：你把 tRPC client 的泛型类型AppRouter传给前端的createTRPCReact，那么前端所有trpc.xxx.yyy.query()调用的入参和出参，都自动从服务端 router 的定义里推导出来。你在服务端改了返回结构，前端不用做任何事，IDE 里马上就会给你划红线。这听起来很玄学，但这是真实存在的开发体验。我做过好几个项目，后期迭代最舒服的地方就是“改字段不用到处找引用”。

但这种闭环也有它脆弱的点：如果你在服务端 handler 里写了any类型、或者在 Prisma 查询结果上强制断言成别的东西，类型安全就形同虚设。所以 t3code 的代码规范里默认是“禁止无理由的as断言”，这个原则我建议你也遵守。另外，React Query 的缓存 key 是 tRPC 自动生成的，你不需要手动管理 cache key，但也因此失去了部分精细控制能力。当你需要强制刷新某个查询时，要用trpc.useUtils().xxx.refetch()，而不是把它当普通 React Query 用法。

2.4 样式方案与 UI 组织

Tailwind CSS 在 t3code 里的配置不算复杂，但它带来的效率提升在实际开发中会被放大得特别明显。t3code 里通常带了一个src/styles/globals.css，里面已经做了 Tailwind 的指令引入，同时还有 CSS 变量的定义。我一般会在模板基础上调整主题色、字体、圆角这些 Design Token，用 Tailwind 的@theme或者 CSS 变量覆盖。

UI 组织还有一个细节：把页面中复用的视觉单元抽成组件。t3code 默认没有安装任何组件库，它的定位是“你可以自己挑选组件库，或者干脆不装”。我实际体验下来很建议做开发的同学自己包一层 UI 基础组件，不要直接每个页面里堆一堆 Tailwind 类名。这样在项目后期，当设计规范变动时，你只需要改一个组件文件，而不是满文件搜索样式类。

3. 实操过程与核心环节实现

3.1 从模板初始化到项目跑起来

我第一次用 t3code 的模板时，初始化命令行其实非常简单：

npx create-t3-app@latest my-app

这里create-t3-app是官方脚手架的安装命令，输入后它会问你选哪些模块：Next.js、Tailwind、Prisma、tRPC、NextAuth，还有要不要用 ESLint。我的建议是：刚开始实践的时候，全部勾上。t3code 这个模板的精髓正是这些模块之间的集成关系，你只挑一部分用，反而会失去“参考栈”的意义。等你已经熟悉了全部集成逻辑，再根据项目需求酌情裁剪。

初始化完成后，必须做四件事来保证项目能跑：

1. 根据提示创建并配置.env文件，把DATABASE_URL指向你的 PostgreSQL 实例。
2. 在prisma/schema.prisma里至少创建一张业务表，然后执行npx prisma migrate dev。
3. 启动npm run dev，访问http://localhost:3000，确认页面正常渲染。
4. 用curl或者直接在页面里触发的 action 测试一下 tRPC 的调用链路。

我在这一步卡过整整一个晚上，原因是模板默认的数据库连接需要那个数据库已存在，而migrate dev不会自动帮你创建数据库——需要先手动createdb一次。如果没有建库，错误提示看起来像是数据库连接失败，但其实是“目标数据库不存在”。模板不会在 README 里给你写这一句，但你在生产上部署时也经常遇到这个情况，最好提前有个印象。

3.2 实现一个完整的 CRUD：从 schema 到前端调用

纸上谈兵再多，不如带着大家写一个完整的 CRUD。我拿“待办事项”举例，一步步看 t3code 每个环节怎么串起来。

第一步，在prisma/schema.prisma中新增一个 Todo 模型：

model Todo { id String @id @default(cuid()) title String done Boolean @default(false) createdAt DateTime @default(now()) updatedAt DateTime @updatedAt userId String user User @relation(fields: [userId], references: [id], onDelete: Cascade) }

然后跑：

npx prisma migrate dev --name add_todo

这条命令做的事情有两件：生成一条 migration 记录并把它提交到数据库，同时重新生成 Prisma Client 的类型。记住，迁移和类型生成是两件事但通常一次搞定。

第二步，在src/server/api/routers/下新建todo.ts，定义几个 procedure：

import { z } from "zod"; import { createTRPCRouter, protectedProcedure } from "~/server/api/trpc"; export const todoRouter = createTRPCRouter({ list: protectedProcedure.query(({ ctx }) => { return ctx.db.todo.findMany({ where: { userId: ctx.session.user.id }, orderBy: { createdAt: "desc" }, }); }), create: protectedProcedure .input(z.object({ title: z.string().min(1) })) .mutation(({ ctx, input }) => { return ctx.db.todo.create({ data: { title: input.title, userId: ctx.session.user.id }, }); }), toggle: protectedProcedure .input(z.object({ id: z.string() })) .mutation(async ({ ctx, input }) => { const todo = await ctx.db.todo.findUnique({ where: { id: input.id } }); if (!todo || todo.userId !== ctx.session.user.id) { throw new TRPCError({ code: "FORBIDDEN" }); } return ctx.db.todo.update({ where: { id: input.id }, data: { done: !todo.done }, }); }), });

然后在根 router_app.ts里把todoRouter挂载上去：

export const appRouter = createTRPCRouter({ todo: todoRouter, });

第三步，前端调用。你在组件里直接写：

const { data: todos, refetch } = trpc.todo.list.useQuery(); const createMutation = trpc.todo.create.useMutation({ onSuccess: () => refetch(), });

这段代码有两个点值得注意。第一，trpc.todo.list能自动提示出来，是因为前端掌握了AppRouter的类型。第二，t3code 默认的 React Query 集成会自动管理缓存失效，但你最好在 mutation 的onSuccess里显式触发 refetch，这样界面更新才即时可靠。

这个完整的 CRUD 流程一旦跑通，你对 t3code 的掌握度就已经超过“会用”了，基本达到了“能复现”的程度。

3.3 鉴权流程与中间件解析

t3code 默认走的鉴权是 NextAuth.js，它在src/server/auth.ts里配置了认证选项。在实际项目中最常见的需求是“登录后访问自己的资源”，比如上面 Todo 里的protectedProcedure。我第一次用这套时犯过一个错，就是以为protectedProcedure会自动把用户 ID 挂到ctx上，但实际上你需要自己在createTRPCContext里把session.user取出来再注入 ctx。

你会在src/server/api/trpc.ts里看到类似这样的结构：

export const createTRPCContext = async (opts: CreateNextContextOptions) => { const { session } = await getServerSession(opts); return { db: prisma, session, }; };

所以protectedProcedure之所以叫 protected，是因为它内部在 middleware 里判断了ctx.session?.user，不存在就抛UNAUTHORIZED。这块如果你想做“记住我”“多设备登录互踢”之类的高级功能，就不能只依赖模板了，需要去扩展 NextAuth 的 session callback 和 database adapter。模板适合做业务验证，但不该把它当成最终产品的最优解，这点要心里有数。

3.4 部署到生产环境的几个关键动作

开发环境下一切正常，不代表部署后也能正常。t3code 部署到 Vercel 或者一台独立服务器上时，有几个常见的坑必须提前规避：

• 数据库迁移不能靠应用启动时自动跑。在 Vercel 上，你不能把prisma migrate deploy放在 build 阶段执行，因为构建环境往往没有数据库访问权限。正确做法是在 CI 里单独跑一条命令，或者提前在本地把 migration 文件推到测试库同步一次。
• 环境变量必须在部署平台显式配置。.env不会被传到 Vercel 或 Docker 里，你需要在部署面板里把DATABASE_URL、NEXTAUTH_SECRET、NEXTAUTH_URL这些值一一填上。尤其是NEXTAUTH_SECRET，不设置的话 NextAuth 在正式环境会直接报错，而不是默默工作。
• PostgreSQL 的连接池配置。Prisma 在 serverless 环境里不能开太高的连接数，建议在schema.prisma里用relationMode = "prisma"并且把默认连接池大小调小一点。这一块配置不对，生产环境很容易出现“连接数打满”导致页面 503。

我在自己的一个真实项目中，用 t3code 模板搭过一个内部数据看板，前端展示实时统计信息，后端对接 PostgreSQL 存历史数据。整个开发周期大约三周，从数据库建模到最终上线，绝大部分时间都花在业务逻辑上，而不是框架调试上。这跟我以前用传统后端框架做全栈项目的体验，差距还是很明显的。

4. 常见问题与排查技巧实录

4.1 类型报错：从满脸问号到习惯成自然

用 t3code 开发，最大的“劝退点”可能就是学习前期的类型报错。最常见的有三类：

一是输入类型不匹配。你会在input()里用 zod 定义了z.object({ id: z.string() })，前端传过来一个number，编译器直接告诉你。这种报错的解决方案不是改类型，而是改调用方，让数据源保持一致。我建议新人在前端入参处多用String()转换，别指望数据库自己帮你解析。

二是session 类型不是你想的那样。NextAuth 的默认 session 类型只包含user.name、user.email和user.image。如果你在 schema 里给 User 模型加了role字段，前端直接读session.user.role会报错。你需要在src/types/next-auth.d.ts里进行模块扩展，把role: "USER" | "ADMIN"声明进去，类型才通。

三是tRPC 的 error 类型太泛。当你用trpc.todo.create.useMutation()时，mutation.error 的类型是TRPCClientError，你无法直接通过error.data.code来做前端差异化提示。我的做法是在 mutation 的onError里打印error.data?.code，根据 code 来映射中文提示信息，比如FORBIDDEN映射成“你没有权限执行此操作”。这种类型太宽是正常的，不是模板缺陷。

4.2 tRPC 与 Next.js 边界：到底哪些逻辑能放前端

我见过一个非常典型的生产事故：开发者在 tRPC procedure 里更新完数据库之后，又在前端组件里直接调用了prisma实例。这在开发模式里跑得好好的，但打包之后前端根本不存在prisma运行时，于是整个页面直接崩溃。t3code 明确把prisma放在src/server/db.ts，**理论上所有 Prisma 调用都只能在服务端。**但这不代表你不会犯错，因为 Next.js 的 Server Component 也运行在服务端，有些人会在 Server Component 里直接 import prisma 做数据查询，这依然是合法的，只是当你在某个 Client Component 里误用use client引用服务端模块时，问题就来了。

排查思路很简单：如果你看到一个报错说“X不能从服务器组件中导入”，那就去检查这个文件是否在顶部声明了"use client"。没有声明的话，它默认就是 Server Component。反之，如果一个文件既想被 Server Component 使用、又被 Client Component 使用，就需要把它拆成两个模块或者保证它只包含可序列化的数据和通用的工具函数。

4.3 构建与部署的经典故障速查

我把实际部署过程中遇到过的问题整理成一张速查表，方便你直接对照排查：

这张表是我反复遇到的情况，你如果在 t3code 上碰到类似问题，基本可以直接按表操作。

4.4 性能优化和体验打磨：模板之上的更进一步

t3code 默认配置偏向“可读性”而非“极限性能”，但如果你的项目规模做到一定程度，有几个优化点值得提前做：

• 数据库查询瘦身。Prisma 会默认查询所有普通字段，如果某张表字段很多，响应体就会无意义地膨胀。你可以在findMany里显式写select，只取需要的字段。这一步对网络性能和内存占用都有明显改善。
• React Query 的缓存策略。首页数据如果不需要强实时，可以把staleTime调大一点，减少无谓的重新请求。t3code 默认的 staleTime 很短，适合开发时看效果，上线后要主动调整。
• 组件懒加载与动态导入。Next.js 自动按路由分包，但页面内的大组件还是要用dynamic()手动懒加载。尤其是图表库、富文本编辑器这些体积大头。

这些优化不是模板替你解决的，而是模板把边界搭好之后你自己需要动手的部分。做完这些，你的项目已经比大多数“能跑就行”的演示项目专业得多了。

5. 从模板到独立项目的扩展路径

5.1 如何把 t3code 改造成业务骨架

t3code 只是一个起点，它不能成为你所有项目的终点。我自己的习惯是，每次用一个新模板都先花 30 分钟“瘦身”：删掉模板自带的示例页面、清空示例 router、重置 Prisma schema，再把基础路由和布局组件搭好。这个动作看起来浪费时间，实际上能帮你彻底理解模板里每一行代码存在的意义，也避免把模板里不符合业务需求的部分带到生产环境。

改造的时候建议遵循“先数据层、后业务层、再页面层”的顺序。很多新人上来先改 UI，结果发现 UI 里调用的接口名字、数据结构都和实际数据层对不上，又回去改接口，来回折腾。先把 Prisma schema 定好、迁移跑通、root router 挂载好，再写页面，你会发现类型安全的优势被发挥到了极致。

5.2 扩展方向：认证、后台、多租户

除了 CRUD 之外，t3code 还能往下延伸的方向其实很多。我目前尝试过比较顺的路线有三个：

一个是后台管理端。基于 Next.js 的/admin路由前缀，配合protectedProcedure加一层requireAdmin的中间件，就能做出一个简单但完整的后台系统。另一个是多租户支持，思路是在每个模型上加tenantId，然后在 tRPC middleware 里根据当前用户的组织信息自动注入过滤条件，这样每个用户只能看到自己租户内的数据。这个扩展做出来，基本就是一个多商户 SaaS 的雏形了。

还有一条路线是给 t3code 装上配套工具链：比如接入 ESLint + Prettier 统一代码风格，接入 GitHub Actions 做 CI，接入 Sentry 做错误监控。这些工具不是 t3code 自带的，但都在 t3code 的“技术观”之内——把类型安全做得足够好，好到错误在本地就被截住了。

5.3 最后聊聊我对这套模板的真实感受

我前后用 t3code 做过企业内部工具、个人作品集网站、还有给团队搭的小型数据平台。每一次的体验都让我越来越确定一件事：前端和后台之间的类型一致性问题，是一个可以用架构解决的工程问题，而不是靠开会和默契来解决的沟通问题。t3code 最了不起的地方不是发明了什么新技术，而是把已经被验证过的工具组合成了一套“开箱即用的好习惯”。

所以如果你是第一次接触这套技术栈，别急着问“它的上限在哪里”，先老老实实照着模板跑通一个完整功能。等到类型安全带来的“舒爽感”真正进入你的日常开发状态之后，你自然会发现，以前那些在接口联调上熬过的夜、为字段对不上而白费的劲，原来都不是必然要经历的。这就是 t3code 这类模板想带给你的最核心的价值。我的建议是，别把它的代码留在某个陈旧仓库里，直接用起来，把模板变成你自己的骨架，遇到问题再回来查这篇清单，多半能把坑填平。