每次新起一个全栈项目，最花时间的往往不是业务代码，而是把脚手架搭到能跑通的状态。装依赖、配 TypeScript、接数据库、加认证、写 CI……这一套流程我重复了不下二十遍，于是决定彻底解决它。t3code 这套方案就是在那个节点上长出来的：它把 Next.js 14、TypeScript、Tailwind CSS、Prisma、tRPC 和一套完整的工程化配置揉在一起，做到 clone 下来就能跑，跑起来就能直接写业务代码。如果你也在做中小型全栈应用、SaaS 雏形、内部工具，或者单纯厌倦了每次从零配环境，这篇分享应该能给你一些可以直接抄走的经验。
1. 为什么会有 t3code：一个"懒人"的工程化执念
1.1 名字的来历：从 T3 Stack 到 t3code
先说名字。T3 最早是 Theo 提出的 T3 Stack 理念，核心就三条：TypeScript 优先、类型安全贯穿全栈、不搞花里胡哨的魔法。t3code 相当于把这个理念进一步工程化——不只是选一堆主流技术，而是把数据库、认证、代码规范、自动化部署全部固定成一套可复用的起点。
我给这套模板取名 t3code，看起来是把 T3 和 code 拼在一起，实际想表达的是“一套符合 T3 精神的代码底座”。它不是某个框架的 fork，也不是什么颠覆性发明，本质上就是一个我反复打磨过的 Next.js 全栈起步项目，只不过把约定、配置、目录结构和示例业务都固化下来了。到今天为止，我用它启动过两个 SaaS 原型、一个数据看板和一个内部运营后台，全部在一天内从零进入业务开发。
1.2 当时遇到的实际痛点
在做 t3code 之前，我开新项目通常是这个流程：create-next-app 初始化、手动加 TypeScript 严格模式、安装 Tailwind、配置 ESLint 和 Prettier、写 Prisma schema、跑 migration、接 NextAuth、再补一个 Docker Compose 起数据库。听起来都是现成工具，但每次都会在版本兼容上耗掉半天。
更头疼的是团队协作。公司里几个项目用的 Next.js 版本不统一，有人用 pages 路由，有人用 app 路由，环境变量命名各写各的，新人 onboarding 光看代码就懵了。我意识到问题不在某个技术选型，而是缺少一个“组织级的默认值”：从目录结构到错误处理，从数据库模型到部署流程，都应该有一套默认约定。t3code 就是把这套约定从脑子里搬到 GitHub 上。
1.3 这个项目适合谁，不适合谁
先泼点冷水。t3code 不是万金油，它能解决的问题非常明确：你需要快速启动一个包含数据库、前后端、认证和 CI 的完整应用，而且你认可“约定大于配置”的做法。
适合这类场景：
- 中小型全栈应用：用户量不大，但需要完整的 CRUD、认证、权限和后台管理。
- SaaS 原型或 MVP：核心是把业务逻辑跑通，而不是研究基础设施。
- 内部工具：比如运营后台、数据看板、审批流程，这类系统重业务轻并发。
- 个人作品集或实验项目：想快速验证某个想法，又不想从零搭环境。
反过来，如果你要做大型微前端、需要深度定制 webpack、或者必须用特定的后端框架（如 NestJS），t3code 并不合适。它是“单体全栈”的思路，不是微服务架构的答案。另外，如果你对底层原理有强好奇心，喜欢自己掌控每一个依赖版本，那模板对你可能反而是一种束缚。工具的意义是服务业务，不是制造争论。
2. 技术选型详解：T3 理念的落地取舍
2.1 框架层：为什么锚定 Next.js 而不是 Vite + Express
我在 t3code 里选用 Next.js 14，不是因为它在社区里最火，而是因为它解决了一个真实问题：全栈应用的双端分离成本。
以前用 Vite 写前端、Express 写后端，看起来职责清晰，实际上要处理两套 TypeScript 配置、两套部署流程、两套运行时代码，接口协议还得自己维护类型。在小团队和单人项目的场景里，这个成本往往比收益还大。Next.js 把前端、API 路由、服务端渲染、静态生成放在同一个应用里，一套代码、一次部署，类型定义可以在服务端和客户端共享，这正好契合 T3 理念里的“类型安全贯穿全栈”。
我还对比过 Remix。Remix 的 loader/action 思路很优秀，表单处理体验好，但它的生态和中间件体系在 2024 年还是比 Next.js 要小一圈。Next.js 的 App Router、Server Components、Server Actions，配合庞大的社区和 Vercel 的部署链路，对于“快速搭建 + 平滑演进”这个目标更稳。如果你完全用 Vercel，那 Next.js 的学习曲线也被平台抹平了不少。
2.2 类型安全的数据流：tRPC 的取舍
tRPC 是 T3 Stack 的灵魂之一。它的思路很简单：你不用手写 REST URI，不用搞 GraphQL schema，只需要在服务端定义一个 router，里面的每个 procedure 自带输入输出类型，客户端直接像调用本地函数一样调用远端方法。
// server/trpc/router.ts import { router, publicProcedure } from "./trpc"; import { z } from "zod"; export const appRouter = router({ getNote: publicProcedure .input(z.object({ id: z.string().uuid() })) .query(async ({ ctx, input }) => { return ctx.prisma.note.findUnique({ where: { id: input.id } }); }), }); export type AppRouter = typeof appRouter;// components/NoteView.tsx import { trpc } from "@/lib/trpc/client"; function NoteView({ id }: { id: string }) { const { data } = trpc.getNote.useQuery({ id }); return <div>{data?.title}</div>; }这段代码里有三个值得注意的点：第一，输入参数用 Zod 定义，运行时校验和 TypeScript 类型是同一个来源；第二，返回类型由 Prisma 查询自动推断，数据库字段变更后，前端调用处会立刻报类型错误；第三，服务端和客户端共享同一个 AppRouter 类型，完全没有手写的接口文档。
有人会说，Next.js 都出 Server Actions 了，还有必要用 tRPC 吗？我的结论是：这不是二选一。Server Actions 适合表单提交和简单变更，tRPC 适合复杂的查询树和程序化调用。t3code 默认内置 tRPC，便于处理多层级查询和缓存策略，但示例代码里也保留了 Server Actions 的用法，开发者可以按接口的复杂度自由切换。没必要为了“统一技术栈”而强迫自己在每个场景都用同一种工具。
2.3 数据层：Prisma 而不是 Drizzle 或 TypeORM
数据层我选 Prisma 5。一个重要原因是它的 schema 声明式设计，让数据库建模变得像写配置文件一样清晰：
model User { id String @id @default(uuid()) email String @unique name String? notes Note[] createdAt DateTime @default(now()) } model Note { id String @id @default(uuid()) title String content String? author User @relation(fields: [authorId], references: [id]) authorId String createdAt DateTime @default(now()) updatedAt DateTime @updatedAt }这是我用 t3code 开发时最常写的模型。schema 改了之后，执行prisma migrate dev --name add_note_model，Prisma 会自动生成 migration SQL 和更新的 TypeScript 类型，不需要手写任何 SQL。对我这种“能少写就少写”的开发者来说，这种工作流太舒适了。
我试过 Drizzle，它在 SQL 贴近性和包体积上有优势，查询语法也更像原生 SQL。但 Drizzle 的 migration 工具和文档在 2024 年仍然比 Prisma 粗糙不少，错误信息也没那么友好。对于团队新人来说，Prisma schema 的声明式模型几乎是零门槛。TypeORM 我也用过，装饰器写实体类和 schema 驱动的 Prisma 相比，维护成本和心智负担都更高。如果你追求极致的 SQL 控制，Drizzle 值得关注；如果你想快速、稳定、少踩坑，Prisma 仍然是更稳妥的默认选择。
2.4 样式与组件：Tailwind 与基础组件
样式层我用 Tailwind CSS 3。这里的取舍不是“原子类 vs CSS 模块”，而是“团队协作时如何保持样式一致性”。Tailwind 的约束系统（spacing、颜色、字号都有 token）天然逼着开发者使用统一的尺度，而不是随手写一个#d4e3fd或者padding: 17px。在 t3code 里我预设了一套主题 token，包括品牌色、中性色、圆角、阴影和安全间距，这样即使有人不熟悉设计规范，也能产出视觉上协调的页面。
组件方面，我在src/components/ui放了一批基于 Tailwind 的基础组件：Button、Input、Card、Badge、Dialog。这些组件的样式没有强绑定任何第三方库，样式可以随时覆盖，你可以把它们当作起点，而不是不可修改的黑盒。说实话，之前我在一些项目里用了重型组件库，后期定制样式反而很痛苦；在 t3code 里我选择“半成品组件”，既保留了设计自由度，又减少了重复劳动。
2.5 工程化三件套：ESLint、Prettier、Husky
自动化规范是 t3code 里最不显眼但最重要的部分。ESLint 我用 9.x 的 flat config，Prettier 固定格式化规则，然后通过 Husky + lint-staged 在提交前自动跑检查：
// package.json 片段 { "lint-staged": { "*.{ts,tsx}": ["eslint --fix", "prettier --write"], "*.{json,css,md}": ["prettier --write"] } }这套流程的意义在于：把“代码规范”从人的自觉变成系统的强制检查。我在团队协作中见过太多因为缩进、引号、命名风格不一致导致的 review 噪音。lint-staged 只检查暂存区文件，跑一次也就一两秒，成本极低收益却很明显。版本锁方面，t3code 使用 pnpm 和lockfile，一方面安装速度快、磁盘占用小，更重要的是锁文件能保证所有开发者的依赖版本一致，还原线上构建的真实情况。
3. 核心实现：t3code 的目录结构与关键代码
3.1 目录结构一览
一个合适的目录结构，应该让新人在 30 秒内找到“接口在哪儿、数据库模型在哪儿、页面在哪儿”。这是 t3code 的地图：
t3code/ ├── prisma/ │ ├── schema.prisma │ └── seed.ts ├── public/ ├── src/ │ ├── app/ │ │ ├── (auth)/ │ │ ├── (dashboard)/ │ │ ├── api/ │ │ │ └── trpc/[trpc]/route.ts │ │ ├── layout.tsx │ │ └── page.tsx │ ├── components/ │ │ ├── ui/ │ │ └── layouts/ │ ├── lib/ │ │ └── utils.ts │ ├── server/ │ │ ├── auth.ts │ │ └── db.ts │ ├── trpc/ │ │ ├── client.ts │ │ ├── router.ts │ │ └── server.ts │ └── styles/ │ └── tailwind.css ├── .env.example ├── .eslintrc.cjs ├── docker-compose.yml ├── next.config.js ├── tailwind.config.ts └── tsconfig.json几个关键决策：src/server下放只能在服务端运行的模块（数据库实例、认证逻辑），src/trpc放 tRPC 的客户端和服务端配置，src/app使用 Next.js App Router 的按路由分组。(auth)和(dashboard)这种带括号的目录名不会被计入 URL，作用纯粹是做代码组织。我会在每层都加一个README.md，用三五行话解释这个文件夹的职责，这比任何架构文档都直观。
3.2 类型安全的三层数据流
t3code 的核心优势在于，你从头到尾写的 TypeScript 类型都是“连着的”。UI 组件里拿到一个Note对象，你不需要去查数据库文档，因为它的类型就是从 Prisma schema 推断出来的。我把这条链路拆成三层：
第一层，数据库到 Prisma 客户端。执行prisma generate之后，@prisma/client会根据 schema.prisma 生成完整的 CRUD 类型，字段名、关联关系、枚举全部都是强类型。
第二层，Prisma 客户端到 tRPC router。在server/routers/note.ts里定义 procedure 时，返回值直接由 Prisma 查询自动推倒。你改动了 schema 的模型字段，编辑器的红波浪线会立刻出现在所有调用这个字段的地方，这比任何代码 review 都有效。
第三层，tRPC router 到 React 组件。客户端通过trpc.note.getById.useQuery()拿到数据，数据类型的来源是服务端 router 的类型导出。这里有一个关键设置：server/trpc/trpc.ts里的createTRPCContext会注入数据库实例和当前用户信息，让每个 procedure 都能访问ctx.prisma和ctx.session。类型安全不是靠“约定”，而是靠这种上下文注入机制在编译期保证的。
3.3 环境变量与配置管理
环境变量是另一个必须严格管理的环节。t3code 把所有需要声明的变量集中在.env.example，并附上注释。最基本的几项：
# 数据库连接串 DATABASE_URL="postgresql://postgres:postgres@localhost:5432/t3code?schema=public" # NextAuth 配置 NEXTAUTH_SECRET="生成一个随机字符串" NEXTAUTH_URL="http://localhost:3000" # 第三方 OAuth（可选） GITHUB_ID="" GITHUB_SECRET=""我不建议在代码里直接到处process.env.XXX，因为环境变量缺失时错误信息非常抽象。t3code 在src/env.ts里用 Zod 做运行时校验：
import { z } from "zod"; const envSchema = z.object({ DATABASE_URL: z.string().min(1), NEXTAUTH_SECRET: z.string().min(32), NEXTAUTH_URL: z.string().url(), GITHUB_ID: z.string().optional(), GITHUB_SECRET: z.string().optional(), }); export const env = envSchema.parse(process.env);这样做的核心价值是：如果某个变量没配，应用会在启动时直接抛出一个带有清晰字段名的错误，而不是等到运行到某个接口时才炸锅。注意，只有以NEXT_PUBLIC_开头的变量才会被打包进浏览器端代码，数据库密码、OAuth Secret 这类敏感值永远不能出现在客户端组件里。我把这条规则写进团队文档，并作为 code review 的必查项。
3.4 数据库模型与种子数据
数据库是每套模板的灵魂。t3code 内置的示例业务是一个简单的协作笔记应用，包含用户、笔记和标签三个模型，覆盖了最常见的关联关系：一对多（User 到 Note）和多对多（Note 到 Tag）。
为了让拿到模板的人可以立刻体验完整的增删改查，我写了一个数据种子脚本prisma/seed.ts，用 faker 生成一批用户和笔记，这样 dev 环境里一进来就有数据看，而不是对着空页面发呆。你可能觉得种子数据无关紧要，但我在实际开发中体会很深：假如每次开新项目都要手动造数据，光这个动作就会消耗一上午，还会劝退很多本来想继续探索的同事。
种子脚本默认只在开发环境执行，生产环境不会运行。你可以通过pnpm db:seed手动触发，也可以在新环境初始化时一键执行。
4. 实操过程：从零搭建一个 t3code 项目
4.1 十分钟快速初始化
先说明，t3code 不是一个发布到 npm 的 create 命令，而是一个 GitHub 模板仓库。我的使用方式很简单：点 “Use this template” 创建新仓库，或者 clone 下来之后改掉 remote。
初始化后的具体步骤，我建议按这个顺序操作：
- 安装依赖：项目使用 pnpm，执行
pnpm install。为什么不用 npm？第一，pnpm 的符号链接机制让依赖安装速度快得多；第二，磁盘占用大幅减少；第三，pnpm-dedupe能更有效地处理依赖重复问题。 - 复制环境变量：执行
cp .env.example .env，然后按需修改。重点检查 DATABASE_URL 和 NEXTAUTH_SECRET，前者决定数据库连接，后者用于会话签名，长度要求至少 32 位。 - 启动基础设施：执行
docker compose up -d启动 PostgreSQL。docker-compose.yml 里我固定了端口映射和数据卷，保证本地开发和 CI 环境完全一致。 - 初始化数据库：执行
pnpm prisma migrate dev，它会根据 schema.prisma 创建数据库表结构，同时生成 Prisma Client 类型。 - 启动开发服务器：执行
pnpm dev，打开 http://localhost:3000 就能看到示例页面。
这套流程我第一次跑通的时候，包括下载依赖在内总共花了不到八分钟。后续再开新项目，因为 Docker 镜像和 pnpm 缓存已经热了，基本五分钟内可以进入写业务代码的状态。
4.2 Prisma 与 PostgreSQL 开发环境
数据库环境的稳定很重要。我在docker-compose.yml里配置 PostgreSQL 的时候，踩过很多坑，所以 t3code 直接内化了几条经验：
services: db: image: postgres:16-alpine container_name: t3code-db restart: unless-stopped environment: POSTGRES_USER: postgres POSTGRES_PASSWORD: postgres POSTGRES_DB: t3code ports: - "5432:5432" volumes: - t3code-data:/var/lib/postgresql/data healthcheck: test: ["CMD-SHELL", "pg_isready -U postgres -d t3code"] interval: 5s timeout: 5s retries: 5 volumes: t3code-data:使用带 healthcheck 的容器很关键。很多人在启动应用时出现PrismaClientInitializationError: Can't reach database server，本质原因就是数据库还没 ready 而应用已经尝试连接。设置 healthcheck 后，如果容器还在启动中，你就可以一眼看出来问题不在代码而在基础设施。另外，把数据放在 Docker volume 里，可以避免容器删除后数据库数据丢失，这在实际开发中太常见了。
开发环境我建议使用 SQLite 进行单元测试，PostgreSQL 用于本地联调和生产环境保持一致。t3code 的测试配置里有一条TEST_DATABASE_URL，测试跑起来不用依赖 Docker 容器，速度更快也更隔离。
4.3 接入认证与权限控制
认证是每个全栈应用都躲不开的部分。t3code 默认集成 NextAuth.js v4，做了两套策略：一套是 GitHub OAuth，适合需要第三方登录的场景；另一套是邮箱 + 密码的 Credentials Provider，适合内部系统。你可以在src/server/auth.ts里按需切换。
import NextAuth from "next-auth"; import GitHub from "next-auth/providers/github"; import Credentials from "next-auth/providers/credentials"; import { PrismaAdapter } from "@next-auth/prisma-adapter"; import { prisma } from "./db"; export const authOptions = { adapter: PrismaAdapter(prisma), providers: [ GitHub({ clientId: process.env.GITHUB_ID!, clientSecret: process.env.GITHUB_SECRET!, }), // 或者使用 Credentials Provider ], session: { strategy: "jwt" }, callbacks: { async jwt({ token, user }) { if (user) token.uid = user.id; return token; }, async session({ session, token }) { if (token.uid) session.user.id = token.uid; return session; }, }, };这里有个非常容易踩坑的地方：NextAuth 默认的 Session 类型里没有user.id，但业务里几乎都要用到当前用户 ID。直接访问session.user.id会报类型错误。t3code 在src/types/next-auth.d.ts里做了 module augmentation，把自定义字段扩展进类型定义，这样你在组件里拿到的 session 就是完整的、带 ID 的类型。
权限控制我采用两层：中间件层做路由守卫，tRPC procedure 层做数据访问控制。比如，编辑笔记的 procedure 必须在getServerSession之后检查ctx.session.user.id是否等于笔记的 authorId，否则直接抛 UNAUTHORIZED。这些逻辑在 t3code 的示例 router 里都写好了，照着改就能复用。
4.4 自动化流程与部署
我把自动化分成两层：代码提交时的检查和发布前的构建检查。
提交时，Husky 钩子触发 lint-staged，对暂存文件跑 ESLint 和 Prettier，只有通过检查的代码才能进入仓库。这么做虽然偶尔会因为格式问题打断提交，但长期看收益巨大——所有历史提交都保持着基本一致的风格，git blame 和 revert 都更干净。
发布前，GitHub Actions 负责跑完整管线。执行顺序如下：
- 安装 pnpm 和依赖。
- 复制
.env.example为.env，并用 GitHub Secrets 覆盖真实变量。 - 执行
prisma migrate deploy更新生产数据库。 - 执行
next build构建生产版本。 - 执行
next lint检查代码规范。 - 运行
vitest run跑单元测试。 - 成功后部署到 Vercel。
部署到 Vercel 是 Next.js 应用最顺滑的路径，但有两个检查项必须提前确认。第一，生产环境的DATABASE_URL一定要配置在 Vercel 的环境变量面板里，而且数据库要允许来自 Vercel IP 的网络访问；第二，NEXTAUTH_URL必须是线上域名，否则登录回调会跳回 localhost。我在第一次部署时才意识到http://localhost:3000这个值不是“无伤大雅”的，它会让 OAuth 流程在线上环境完全不可用，排查了半小时才定位到问题。
5. 常见问题与排查实录
5.1 Prisma 引擎报错：engine not found
在 Next.js 项目里用 Prisma，最经典的坑是PrismaClientInitializationError: PrismaClientInitializationError: Engine not found。产生原因有两个：一是prisma generate生成的客户端和当前运行环境不匹配，二是 Next.js 在 edge runtime 下调用 Prisma 时，二进制引擎无法加载。
我在 t3code 里采用的标准解法是，在prisma/schema.prisma里显式声明生成的客户端输出目录，并在server/db.ts里避免动态生成 PrismaClient：
generator client { provider = "prisma-client-js" output = "../src/generated/prisma" }注意不要在模块顶层之外创建 PrismaClient 实例，避免 Next.js 热更新时产生多个数据库连接导致连接数耗尽。全局单例的写法在 t3code 里用了十几次，一次连接问题都没再出现过：
import { PrismaClient } from "@/generated/prisma"; const globalForPrisma = globalThis as unknown as { prisma?: PrismaClient }; export const prisma = globalForPrisma.prisma ?? new PrismaClient(); if (process.env.NODE_ENV !== "production") globalForPrisma.prisma = prisma;如果是在 Server Components 或 API 路由里使用，也尽量别用await prisma.$connect()，Prisma 的惰性连接机制会自动处理连接池。手动提前连接反而容易在 serverless 环境里造成无謂的启动开销。
5.2 tRPC 在 App Router 下返回 404
tRPC 的 API 路由在 App Router 里必须放在约定位置：src/app/api/trpc/[trpc]/route.ts。注意，[trpc]是动态路由段，如果你不小心把文件名改成route.tsx或者把目录写成了app/api/trpc/route.ts，请求就会 404。
完整的 route handler 如下：
import { fetchRequestHandler } from "@trpc/server/adapters/fetch"; import { appRouter } from "@/server/routers"; import { createTRPCContext } from "@/trpc/server"; const handler = (req: Request) => fetchRequestHandler({ endpoint: "/api/trpc", req, router: appRouter, createContext: createTRPCContext, }); export { handler as GET, handler as POST };我建议你在刚配置完 tRPC 之后，先在浏览器直接访问http://localhost:3000/api/trpc/getNote?input={"id":"xxx"}，确认接口能返回 JSON 而不是 404、HTML 或者其他错误页。先验证路由层，再接前端调用，排查范围能缩小很多。
另一个常见的混淆点是端点和 procedure 路径：trpc.getNote.useQuery()对应的服务端路径通常是/api/trpc/getNote，如果你的 tRPC router 里还有多层级命名空间，输入参数需要按 tRPC 的 JSON 格式编码。好在客户端库会帮你处理好，只要服务端 endpoint 和路由文件名一致就行。
5.3 环境变量未同步导致的构建失败
我见过太多次“本地好好的，生产构建失败”的场景，原因十有八九是环境变量问题。这里有两种情况需要区分。
第一种是生产构建时缺少DATABASE_URL。Next.js 构建过程中，如果某个页面是静态渲染的，并且它调用了prisma.note.findMany()，那么构建时会真正执行数据库查询。数据库连不上，构建直接失败。解决思路有两个：要么确保构建环境能访问生产数据库（通过 CI Secrets），要么给页面加上dynamic = "force-dynamic"，让它在请求时才执行数据库查询，而不是构建时。
第二种是NEXT_PUBLIC_前缀的变量在构建时是内联进 JS 的。这意味着你在运行时改环境变量是不会生效的，必须在next build之前就配置好。在 t3code 里我对这类变量加了 Zod 校验，虽然着眼点是类型安全，但也顺带会暴露“构建时缺变量”的问题，从一开始就让错误明明白白。
5.4 NextAuth 的类型问题与中间件陷阱
NextAuth 在 TypeScript 下体验不错，但类型扩展不写对就是灾难。如果你在组件里访问session.user.id报错 “Property 'id' does not exist on type 'User'”，不用怀疑，就是缺了类型扩展声明。t3code 在src/types/next-auth.d.ts里完善了这一层，建议你把自定义字段都按同样的方式扩展：
import { DefaultSession } from "next-auth"; declare module "next-auth" { interface Session { user: { id: string; } & DefaultSession["user"]; } }中间件层的陷阱在于 matcher 配置。默认情况下，middleware 里如果没有精确的 matcher，Next.js 会在所有请求上都跑一遍，开发时还好，生产时会影响性能甚至误伤静态资源。t3code 的middleware.ts里限定只保护进入 dashboard 和 api 的请求：
export const config = { matcher: ["/dashboard/:path*", "/api/trpc/:path*"], };我遇到过一次非常隐蔽的问题：middleware 里用getToken时没有传secret，开发环境因为 NEXTAUTH_SECRET 存在所以正常，部署到 Vercel 后由于环境变量同步延迟导致secret缺失，所有登录用户都被弹回登录页。后来我养成了一个习惯：middleware 里的 secret 必须显式从环境变量读取，不要依赖任何隐式默认值。这个习惯在 t3code 的排查文档里也作为第一条写了进去。
5.5 其他值得留意的小坑
除了上面四大类，还有一些高频出现的小问题，我整理到这里，当作一个快速索引：
- Tailwind 类名顺序和覆盖问题：如果你用了自定义组件库，注意 Tailwind 的类名优先级完全取决于 CSS 文件中类的顺序，不是 class 属性里的书写顺序。想覆盖组件默认样式时，直接在同名类上修改可能会失效，更好的做法是通过 props 传递 className，并在组件内部用
cn()合并工具（t3code 用的是clsx+tailwind-merge）。 - Prisma 迁移冲突：两个人同时改了 schema，执行
migrate dev时可能报 migration 冲突。我的建议是小项目用单一主分支，避免并行开发同一个数据模型；如果冲突已经发生，不要手动删 migration 文件，用migrate resolve标记 rollback。 - Docker 容器端口占用：如果本地 5432 端口已经被其他项目占用，docker compose up 会失败。可以改用映射到其他端口，比如
5433:5432，然后同步修改 DATABASE_URL。 - pnpm 安装慢或下载失败：国内网络环境下可以配置镜像源，但注意 lockfile 里的 integrity 校验不能丢，否则团队环境会不一致。
6. 写在最后：t3code 现在在我手里是怎么用的
做完 t3code 之后，我的开发习惯其实也被它反向塑造了。现在我接一个新的内部需求，第一反应不是从空白项目开始，而是直接 clone t3code，改掉 README 和应用名，然后开始写业务。我记得有一次带一个实习生做运营后台，他第一次接触 Next.js 和 Prisma，给他看 schema.prisma 和几个 tRPC router 之后，他很快就能照着写新的 CRUD，不再需要我一遍遍解释“接口在哪定义”“数据库表怎么加”。
如果你打算使用 t3code 或者模仿它的思路，我想分享两个额外的经验。第一，模板的价值不在于“技术多新”，而在于“决策已经被做出”。很多项目卡住的点不是某一项技术不会用，而是没有人为这些问题做过默认决定——数据库用哪个？认证用什么方案？目录怎么分？当你把决定固化下来，团队精力就能集中在业务上。第二，模板也需要持续维护。我自己大约每隔几个月，会审视一遍依赖版本、废弃 API 和新的 Next.js 特性，把它更新到当前推荐实践。模板不是古董，它是在你业务旁边一直活着的一条代码路径。
最后再分享一个小技巧：每次用 t3code 开启新项目时，我会顺手写一个docs/decisions.md，把这次项目里所有“为什么选这个方案”记录下来。半年后回头看，这些决策记录比代码本身更能帮你理解当时的业务约束和取舍。工程化的终点不是消灭决策，而是让每次决策都有迹可循、可以被复盘。t3code 就是这样一套起点，剩下的路，交给你的业务去走。
