1. t3code 项目概述：把类型安全全栈应用的“工程债”一次还清
先开门见山，t3code 是我最近在团队内部落地的一个全栈脚手架项目。它不只是一个create-next-app的二次封装，也不是网上那种只丢给你一个 README 的模板仓库，而是一套完整的、可以拿到生产环境直接迭代的 T3 Stack 工程化底座。核心关键词就是“T3”——TypeScript、Tailwind、tRPC，再加上 Next.js 和 Prisma，五个东西拧成一股绳，让前端、后端、数据库三层的类型定义在编译期就对齐，而不是等接口联调时才发现字段名写错。
你可能会问，市面上的脚手架那么多，create-t3-app 本身也很好用，为什么我还要自己搞一个 t3code？原因很简单：create-t3-app 给你的是一张白纸，而 t3code 给的是一个已经画好了墙线、布好了水电、甚至装了部分家具的房间。实际开发中，团队真正浪费时间的不是“搭框架”，而是“定规范”——目录怎么分、API 怎么写、权限怎么控、错误怎么报、部署怎么配。这些决策每个项目都要重做一遍，每做一个新项目就重复踩一遍坑。t3code 就是为了把这些“工程债”一次性还掉，让业务开发从第一天就进入正轨。
适合谁看？我先说清楚，如果你只是想做个简单的静态博客，t3code 对你来说太重了；但如果你正在做一个需要登录、需要操作数据库、需要前后端交互的中后台或 SaaS 应用，或者你所在的小团队想统一全栈项目的最佳实践，这篇内容值得认真读一遍。下面我按实际的落地顺序，把整个项目的设计思路、技术选型、实操步骤和踩坑记录完整拆开讲。
1.1 为什么会有 t3code：从“能跑”到“能维护”的最后一公里
老实说，任何一个熟悉 Next.js 的人，用官方脚手架拉一个项目出来跑通 demo 都不难。真正让人头疼的是项目跑到三个月以后：类型定义散落各处，API 路由的入参出参全靠肉眼对齐，数据库字段改了但前端组件忘了改，结果运行时才发现undefined满天飞。T3 Stack 的核心价值不在于“新”，而在于它把类型安全的理念贯穿到了全栈的每一条数据通路上。
t3code 这个项目的出发点，就是把我这些年做全栈项目时积累的“标准答案”沉淀成代码。比如，我要求所有 API 的入参必须经过 Zod 校验，所有数据库查询必须通过 Prisma Client 的强类型 API 访问，所有前后端数据交换必须走 tRPC 的 procedure 而不是手写 fetch。这些约束在项目初期看起来像是“多此一举”，但到了中期维护和功能迭代时，它的价值会成倍放大——因为编译器会在你写错的时候直接报错，而不是等用户点到那个页面才崩。
另一个现实动机是团队协作。几个人同时在一个仓库里干活，如果没有统一的代码结构和约定，Git 冲突和“这代码谁写的”就会成为日常。t3code 预设了清晰的目录边界和分层规范，新人进来照着已有模块抄就能写出风格一致的功能，code review 的成本也大幅下降。这一点对于小团队和外包团队尤其重要。
1.2 t3code 适合谁，解决了哪些具体痛点
我把目标用户分成三类，你可以对号入座：
第一类是独立开发者。一个人要写前端、后端、数据库，本来就分身乏术，t3code 能帮你把“技术选型纠结”直接消掉，用一套已经被验证过的方案快速出活。第二类是小团队的技术负责人。你需要为团队定一套默认技术栈，减少沟通成本，t3code 的规范和约束能让成员们在同一个框架内协作。第三类是全栈学习者。如果你已经会 React 和基础 Node.js，但不知道如何把后端和数据库优雅地接进来，t3code 的代码结构本身就是一份不错的学习样本。
对应的痛点也很明确：不折腾环境配置、不纠结 REST 还是 GraphQL、不怕表结构设计乱、不担心部署方案翻车。t3code 把从“git clone 下来”到“部署上线能跑通”的整个链路都验证过一遍——这正是多数脚手架没有做到位的地方。
2. 核心技术栈拆解：T3 Stack 选型背后到底在想什么
这一节我会逐个解释 t3code 里每个技术选型的“为什么”。很多文章只告诉你“T3 Stack 很火”，但不告诉你它为什么能在实际项目中站得住脚。只有理解了每一层的设计意图，你才敢在遇到问题时自己做调整。
2.1 Next.js App Router：为什么是它而不是 Vite 或 CRA
先说框架底座。t3code 选用 Next.js 14+ 的 App Router 作为应用骨架，原因有两个：一是服务端组件（RSC）天然适合处理首屏性能和 SEO 场景，二是 App Router 的布局系统和路由约定能让页面结构非常清晰。相比之下，Vite + React 的 SPA 方案在需要 SEO 或复杂路由时会额外引入 react-helmet 和路由配置，而这些在 Next.js 里都是内置能力。
你可能担心 App Router 的学习曲线。说实话，从 Pages Router 迁移到 App Router 确实有一些心智负担，比如server和client组件的边界划分。但 t3code 在项目结构里已经把边界画清楚了：默认所有页面组件都是服务端组件，只有需要交互的局部（比如表单、按钮、动态列表）才显式标记use client。这个约定让团队不必每写一个组件都做判断，统一按“尽量服务端”的规则走就行。
实际项目中我还验证过一件事：App Router 的缓存策略（静态渲染 + 动态渲染混合）配合 tRPC 的查询，可以做到接口数据只在需要时才会触达数据库，而不是每次刷新页面都重新拉取。这样首屏体验和 TTFB 都在可接受范围，不需要为了性能做额外的 SSR 服务端缓存层。
2.2 tRPC + Prisma：前后端类型安全的“命中注定”
如果只说一个让我坚定选择 T3 Stack 的理由，那就是 tRPC。过去写接口，前端要维护 API 类型定义、后端还要重复写一遍校验逻辑，两边不同步就出问题。tRPC 的精髓是：你一旦在后端定义了 procedure 的输入输出类型，前端调用时就直接拥有完整的类型提示和编译期检查，不需要生成 SDK，不需要手写类型声明文件。这种体验用一句话形容就是“调用后端方法像调用本地函数一样安心”。
配合 Prisma，类型安全的链路就彻底打通了。Prisma Schema 是数据库模型的唯一事实来源，由它自动生成 Prisma Client 类型；tRPC router 里的查询和变更都基于 Prisma Client 的返回类型推导；前端组件再通过 tRPC 的 hooks 拿到这些类型。整条链路上任何一环改了字段，TypeScript 编译器都会立刻告诉你哪些地方需要同步修改。这个特性在日常开发中的价值怎么强调都不过分——它等于给你的项目装了一套自动化的“接口契约测试”。
有人会问，那 GraphQL 不是也能做类似的事吗？确实，但 GraphQL 的代价是复杂的 schema 设计和额外的 codegen 流程，还要面对缓存策略和权限解析的复杂性。在小团队和快速迭代的场景里，tRPC 的轻量直接是一种务实的妥协。
2.3 Tailwind CSS 与样式方案：不写 CSS 类名之争
样式方案我选择了 Tailwind CSS。说实话，这套方案在国内团队里争议挺大，喜欢的人很喜欢，讨厌的人觉得“class 名比内联样式还长”。我的立场是：Tailwind 的核心优势不在于好看，而在于把样式的修改范围控制在组件内部，避免团队写全局 CSS 导致样式污染。t3code 里预设了基于设计令牌的 Tailwind 配置，包括颜色、字体、间距、阴影的语义化变量，组件里不直接写魔法数值。
同时，我也保留了 CSS Modules 的出口——如果某个组件的样式特别复杂（比如复杂动画、特殊布局），可以在同目录下写一个.module.css文件，Tailwind 和 CSS Modules 可以优雅共存。这样既不强制所有人用同一种风格，又避免了“只能二选一”的束缚。
值得一提的还有暗黑模式。t3code 内置了基于next-themes的主题切换，默认使用 CSS 变量而不是 Tailwind 的 dark 变体硬切换，这样后续做品牌定制时只需改动根的 CSS 变量即可。这个细节很多人会忽略，但真到了客户要求“换个品牌色”时，你就知道这有多省事了。
3. t3code 的目录结构与初始化实操：从 clone 到跑通
空谈设计没有意义，这一节直接上实操。我会按“初始化项目 → 配置核心文件 → 跑通一个完整 CRUD”三个阶段带你走一遍，把关键的代码和配置列出来，并解释每一步背后的思考。
3.1 项目初始化与工程配置：5 分钟先跑起来
t3code 已经是一个完整的仓库，你只需要 Clone 下来安装依赖即可。不过我更建议你先从空项目走一遍流程，这样能理解每个配置文件存在的意义。整个初始化流程如下：
# 1. 克隆仓库（或基于模板创建） git clone https://github.com/your-org/t3code.git my-project cd my-project # 2. 安装依赖 pnpm install # 3. 初始化环境变量 cp .env.example .env # 4. 启动数据库（默认支持 Postgres 和 SQLite） docker compose up -d db # 或者本地开发时直接用 SQLite，免去容器依赖 # 5. 生成 Prisma Client 并执行迁移 pnpm prisma:generate pnpm prisma:migrate # 6. 启动开发服务器 pnpm dev依赖管理我选择 pnpm 而不是 npm/yarn，最大的理由是磁盘占用和安装速度。全栈项目的 node_modules 动辄上千 MB，pnpm 的硬链接机制能省下大量空间，而且在 CI 环境里安装速度明显更快。当然，如果你团队习惯用 yarn，t3code 也兼容，只需要替换 lockfile 即可，我不会在这上面做强绑定。
环境变量方面，.env.example里预设了关键项：DATABASE_URL（数据库连接串）、NEXTAUTH_SECRET（认证密钥）、NEXTAUTH_URL（回调地址）等。这里有一个常见坑：NEXTAUTH_SECRET如果你不设置，NextAuth 在开发环境会用随机值，但部署到线上时 session 会在重启后失效。所以 t3code 里我已经写了一段脚本，首次初始化时自动生成一个随机密钥写入.env.local。
3.2 核心目录结构：每一层放什么、为什么这么放
t3code 的目录结构是经过多次调整后定下来的，我直接贴出来并逐层解释：
src/ ├── app/ # Next.js App Router 页面层 │ ├── (auth)/ # 认证相关路由分组 │ │ ├── login/ │ │ └── register/ │ ├── (dashboard)/ # 业务主界面路由分组 │ │ ├── projects/ │ │ └── settings/ │ ├── api/ # 极少使用的 API Route（仅用于回调等） │ ├── layout.tsx # 根布局 │ └── page.tsx # 首页 ├── components/ # 通用组件 │ ├── ui/ # 基础 UI 组件（Button、Input...） │ └── shared/ # 业务共享组件 ├── server/ # 服务端逻辑（不会打进客户端 bundle） │ ├── api/ # tRPC router 定义 │ │ ├── routers/ │ │ └── root.ts │ ├── db/ # Prisma Client 实例 │ └── auth/ # NextAuth 配置与权限逻辑 ├── trpc/ # tRPC 客户端封装（server caller & client hooks） └── lib/ # 通用工具函数、常量这里最关键的规则是：所有涉及数据库和文件系统的代码都必须放在src/server/下，组件层只能通过 tRPC 调用它们。这个物理边界直接保证了客户端 bundle 不会意外引入 Node.js 依赖——如果你不小心在组件里import了 Prisma，Next.js 的编译警告会立刻提醒你。这比靠 eslint 规则硬约束要可靠得多。
app/路由下我用了“路由分组”（带括号的目录）来组织认证区和业务区。这样做的目的是共用同一套根布局，但认证区不需要的侧边栏和导航可以在各自的 layout 里单独定义。项目的扩展性也因此更好——比如以后加一个独立的 admin 后台，只需要新增一个(admin)分组，原代码完全不用改动。
3.3 核心实现：跑通一个带校验和权限的项目 CRUD
理论说再多，不如写段真实的代码。下面我以一个“项目（Project）”资源的完整 CRUD 为例，展示 t3code 里从数据库到前端页面的标准路径。
第一步，定义 Prisma Model：
model Project { id String @id @default(cuid()) name String slug String @unique ownerId String owner User @relation(fields: [ownerId], references: [id], onDelete: Cascade) status String @default("active") createdAt DateTime @default(now()) updatedAt DateTime @updatedAt }这里有两个细节值得注意：主键用了cuid()而不是自增 id，因为分布式环境下自增 id 会产生竞态和预测风险（你也不想让别人通过 id 猜到你的业务量）；slug字段设了唯一索引，后续做用户可访问的公开页面时会很方便。
第二步，定义 Zod Schema 来做输入校验。所有 tRPC 的输入参数我都要求必须有 Zod Schema，这不只是形式主义，而是因为 Prisma 的类型并不含运行时的业务校验规则。比如状态字段只允许特定值、name 长度有要求，这些都需要显式校验。
import { z } from "zod"; export const projectCreateSchema = z.object({ name: z.string().min(2).max(50), slug: z.string().regex(/^[a-z0-9-]+$/), status: z.enum(["active", "archived"]).default("active"), }); export const projectUpdateSchema = projectCreateSchema.partial();第三步，定义 tRPC router：
import { createTRPCRouter, protectedProcedure } from "../trpc"; import { projectCreateSchema, projectUpdateSchema } from "../../lib/validations/project"; import { TRPCError } from "@trpc/server"; export const projectRouter = createTRPCRouter({ // 查询当前用户的项目列表 list: protectedProcedure.query(({ ctx }) => { return ctx.prisma.project.findMany({ where: { ownerId: ctx.session.user.id }, orderBy: { createdAt: "desc" }, }); }), // 创建项目，自动把当前用户设为 owner create: protectedProcedure .input(projectCreateSchema) .mutation(async ({ ctx, input }) => { return ctx.prisma.project.create({ data: { ...input, ownerId: ctx.session.user.id, }, }); }), // 只能操作自己的项目，否则抛 403 update: protectedProcedure .input(projectUpdateSchema.extend({ id: z.string() })) .mutation(async ({ ctx, input }) => { const existing = await ctx.prisma.project.findUnique({ where: { id: input.id }, }); if (!existing || existing.ownerId !== ctx.session.user.id) { throw new TRPCError({ code: "FORBIDDEN" }); } return ctx.prisma.project.update({ where: { id: input.id }, data: input, }); }), });第四步，前端调用：
const utils = api.useUtils(); const { data: projects, isLoading } = api.project.list.useQuery(); const createProject = api.project.create.useMutation({ onSuccess: () => { utils.project.list.invalidate(); }, }); // 调用时 createProject.mutate({ name: "Demo", slug: "demo" })这里有一个容易被忽视的细节：update的FORBIDDEN检查不能省略。很多人觉得“登录了就行”，但多租户应用里如果不做资源归属校验，就会出现用户 A 改用户 B 数据的越权漏洞。这个操作在 t3code 里已经封装成通用的assertResourceOwner工具函数，你只需要传资源和当前用户即可。
4. 部署、安全与常见问题排查实录
项目能跑只是第一步，能上线稳定运行才是真正的考验。t3code 在设计之初就把部署和运维纳入了考虑范围，但这部分也是踩坑最多的地方。我用一整节来梳理，保证每条经验都是踩过坑才得出的。
4.1 部署方案：Vercel 与 Docker Compose 两条路线
t3code 支持两种主流部署方式，按项目阶段选择即可。
路线一：Vercel（适合前端为主、依赖托管数据库的团队）
由于 t3code 本身是 Next.js 项目，Vercel 的集成度最高。部署时需要设置环境变量（DATABASE_URL、NEXTAUTH_SECRET等），然后连接 GitHub 仓库，每次 push 会自动构建部署。我建议将数据库使用托管服务（比如 Neon 或 Supabase），避免自己在服务器上维护 Postgres 实例。Vercel 的 Serverless 环境是无状态的，所以关于文件上传的需求就不要用本地磁盘了，直接用 S3 或 Cloudflare R2。
有一个细节需要注意：Vercel 对 Serverless Function 的大小有限制（默认 50MB，扩展后 250MB）。如果你的 Prisma Engines 比较大，建议在next.config.js里关闭一些不必要的依赖打包，或者使用 Prisma 的 driver adapter 方案，让 Prisma Client 在 Edge Runtime 也能跑。t3code 默认启用了这个优化，但如果你加了额外的二进制依赖，需要留意构建产物体积。
路线二：Docker Compose（适合需要自托管、或数据库与应用必须内网互通的团队）
t3code 提供了生产环境的Dockerfile和docker-compose.yml示例。由于 Next.js 是服务端渲染，Docker 部署需要处理多阶段构建、静态资源输出和端口反代等细节。我整理了一个最小可用的Dockerfile如下：
FROM node:20-alpine AS deps RUN apk add --no-cache libc6-compat openssl WORKDIR /app COPY package.json pnpm-lock.yaml ./ RUN corepack enable && pnpm install --frozen-lockfile FROM node:20-alpine AS builder WORKDIR /app COPY --from=deps /app/node_modules ./node_modules COPY . . RUN npx prisma generate RUN pnpm build FROM node:20-alpine AS runner WORKDIR /app ENV NODE_ENV=production RUN addgroup -S nodejs && adduser -S nextjs -G nodejs COPY --from=builder /app/public ./public COPY --from=builder --chown=nextjs:nodejs /app/.next/standalone ./ COPY --from=builder --chown=nextjs:nodejs /app/.next/static ./.next/static USER nextjs EXPOSE 3000 CMD ["node", "server.js"]如果你使用pnpm，记得在安装依赖时开启 corepack；如果你用 Prisma 且数据库连接串里需要 SSL 证书，可能还要额外拷贝证书文件进 runner 阶段。这里最隐蔽的坑是openssl依赖，Alpine Linux 默认不带这个共享库，Prisma 运行时会直接崩，必须在 deps 阶段安装。
4.2 开发调试中常见的 6 个问题与解决方案
按我实际遇到和收集的团队反馈，我把最高频的 6 个问题整理成表格，方便随时查阅：
| 问题现象 | 根本原因 | 解决方案 |
|---|---|---|
| 改了 Prisma Schema 后查不到新字段 | 没有重新prisma generate | 每次改 schema 后执行pnpm prisma:generate，或加 watch 脚本 |
| 服务端组件里调用 tRPC 报错 | 在 Server Component 中直接用了apihooks | 使用 t3code 提供的createCaller的 server 端调用方式 |
| NextAuth 登录回调到不了目标页面 | NEXTAUTH_URL没设置或反向代理配置错误 | 在部署环境显式设置NEXTAUTH_URL，本地开发用 localhost |
| 部署后图片资源 404 | 使用了本地内存/磁盘存储 | 改用 S3/R2 等对象存储，并在组件层封装统一的图片 URL |
| 构建时 Typescript 类型报错但本地通过了 | 本地 node_modules 版本和 CI 不一致 | 固定 CI 的 package manager 版本并开启--frozen-lockfile |
| 页面正常但 API 请求一直 loading | tRPC 的 query key 缓存问题 | 检查是否在useQuery里传了非序列化参数，或没有正确调用invalidate |
其中第二个问题值得展开讲一下。t3code 同时支持两种调用 tRPC 的方式：一种是在 Client Component 中用api.post.list.useQuery()这种 hooks 方式；另一种是在 Server Component 中通过createCaller直接调用 procedure。如果你需要在一个页面同时用到两者，务必注意：服务端调用会直接执行数据库查询，而客户端调用会发起 HTTP 请求。如果同一页面重复调用同一个查询，就会多发一次网络请求。t3code 里的最佳实践是：首屏需要的核心数据尽量在 Server Component 里取，交互产生的增量数据在 Client 里用 hooks 管理——这样既能保证类型安全，又能节省网络开销。
4.3 性能与安全：哪些红线不能踩
性能优化的头号准则是：不要无脑地在客户端渲染整棵页面树。t3code 默认的页面组件尽可能保持 Server Component 形态，只有在需要监听键盘输入、管理本地状态时才在局部引入 Client Component。你可以在 Next.js DevTools 里查看每个组件的“客户端/服务端”标记，如果发现一个简单的列表页被标记成了 Client，大概率是因为你不知不觉在父组件里引入了浏览器 API 依赖，导致整个子树都变 Client。
数据库层面，Prisma 最常见的性能杀手是 N+1 查询。t3code 的规范要求列表查询时显式使用include或select来控制返回的数据粒度，不要图省事直接findMany返回整个表的所有字段，更不要在一个循环里逐条查外键。举个例子，如果你要展示 20 个项目以及每个项目的负责人姓名，就应该用：
ctx.prisma.project.findMany({ where: { ownerId: ctx.session.user.id }, include: { owner: { select: { name: true } } }, });而不是先查 20 个项目再循环查 20 次 owner。这个问题在本地数据量小的时候完全看不出，但一上线数据量上去就会立刻变成灾难，而且很难查。
安全方面，除了前面提到的资源归属校验，还要注意日志脱敏。t3code 里的 logger 工具默认过滤了password、token、authorization等敏感字段，避免在错误上报时把用户密码或会话令牌打到日志平台。这个小细节你也许觉得没必要，但一旦发生过安全事件，你就知道数据脱敏有多重要了。
5. 基于 t3code 的扩展实践：我踩过的坑和沉淀下来的经验
脚手架类的项目，真正的价值不在第一版能跑通，而在长期迭代中不断沉淀。我现在把个人实践中总结的几条经验和后续设想写出来，供你参考。
第一点是版本锁定要狠心。t3code 刚发布时，我为了“方便升级”使用了依赖的^范围符号，结果没过两周 Next.js 出了一个小版本更新，某个深层依赖的行为变了，导致部署到 Vercel 后出现诡异的缓存问题。后来我把所有核心依赖的版本号都固定为精确版本，并在 CI 里运行pnpm approve-builds和依赖比对脚本，确保本地与线上依赖树完全一致。也许你会觉得“锁版本”限制了升级灵活性，但全栈项目出问题的成本远大于升级的收益，一个稳定的底座比什么都重要。
第二点是文档要跟上代码变更。t3code 的 README 最初写得很完善，但随着项目演进，有一些推荐用法变了（比如从 Pages Router 迁移到 App Router 时，很多 API 签名变了），文档一度过时。现在我要求团队里任何一次调整文件结构或配置约定的 PR，必须同步更新对应文档段落。文档不完美没关系，但不能不更新，这是长期维护大型项目的底线。
第三点是不要把脚手架变成约束的枷锁。有些团队会把 scaffold 里的规则当成铁律，每个新功能都得在框架内“挤”出来——长此以往，开发体验会变得疲惫。t3code 里我特意留了一条“逃生通道”：如果某个模块确实不需要类型安全链路的深度集成（比如一些纯静态的营销页），你可以不通过 tRPC 而是直接用 Server Component 写数据库查询。这个口子可以让开发者在合适的时候绕路，而不是奉“最佳实践”为教条。真正好的工程化是让你少做决定，而不是剥夺所有决定权。
最后聊一个关于“这个项目还能怎么扩展”的设想。我现在已经在准备 t3code 的第二个版本：计划加入基于 RFC 的文档自动生成工具（从 Zod Schema 直接渲染字段说明），以及一个可选的 Admin 面板生成器（通过 Prisma 模型自动生成基础的后台 CRUD 界面）。前者能解决团队后期维护接口文档的痛点，后者能提升中后台项目的交付速度。如果你也在维护类似的内部全栈脚手架，强烈建议你在“文档自动化”和“CRUD 代码生成”这两个方向上多投入一点——这是 ROI 最高的两个扩展点。
项目从 0 到 1 往往靠的是初期的激情，但从 1 到 100 靠的全是这些不起眼的工程细节。t3code 对我来说已经不只是一个代码仓库，更像是我对全栈工程化理解的一个载体。希望这篇拆解能给你带来一些实际的启发，哪怕只是让你少踩我踩过的一个坑，也算没白写。如果你也正在做类似的脚手架，或者对某些技术选型有自己的看法，欢迎找机会一起交流。
