t3code 是我从去年开始一直在打磨的一个全栈脚手架项目。简单说，它用一条命令把 TypeScript、Tailwind、tRPC、Prisma 这一整套技术栈的工程底座搭好，再根据你定义的数据库模型，自动生成从后端接口到前端页面的完整 CRUD 链路。我最初做这个工具，是因为每次开新项目都要花小半天处理重复的初始化工作，团队里每个人搭出来的结构还不一样。t3code 解决的就是这个“从零开始”的痛点，适合中小型全栈团队使用，也适合一个人写全栈项目时不想在框架配置上浪费时间的人。这篇文章我会从设计思路、核心逻辑、实操步骤到排查经验，完整拆一遍这个项目。
1. t3code 是什么，我为什么要做这个工具
1.1 项目背景：从一次次手工搭环境里憋出来的想法
先说背景。以前我开一个新项目，流程基本是这样的：打开 Next.js 官方脚手架，再手动装 Prisma、Tailwind、tRPC、zod、ESLint、Prettier，然后花时间把 TypeScript 的路径别名配好，把环境变量模板建好，把 API 路由的目录结构理清楚。这些步骤单个看都不复杂，但串起来就是小半天。更麻烦的是，每次装的版本可能不一样，官方脚手架更新后目录结构也会变，于是每个项目的工程化配置都长得不太一样。
后来带团队，问题更明显。团队里五个人，每个人开新项目都有自己的一套习惯。有人喜欢把数据库操作写在 controllers 里，有人习惯全部塞在 API route 里，有人用services目录，有人不用。代码风格不一致倒还好，真正麻烦的是公共逻辑没法复用，新人来了之后看哪个项目都觉得陌生。我当时的想法很简单：能不能把项目初始化变成一件“选择模板”而不是“搭积木”的事。
这算是 t3code 的起点。t3code 这个名字里的 T3，指的是 TypeScript、Tailwind、tRPC 这个组合。code 则代表了它的定位——不只帮你把项目壳子搭好，还会根据模型定义去生成真正的业务代码。你可以把它理解成一个“会写代码的脚手架”，结构模板是它的骨架，数据库模型是它的输入，输出的是可以直接跑起来的前后端模块。
1.2 t3code 解决的核心问题
我梳理了一下，t3code 主要解决四个问题。
第一是初始化时间。传统方式从执行create-next-app到项目能跑起来，快的半小时，慢的半天。t3code 把整个初始化过程收敛到一条命令，交互式问完几个选项后，生成一个已经配好 Prisma、tRPC、Tailwind、ESLint、Prettier、Dockerfile 的完整项目，跑起来的时间可以压缩到十分钟以内。
第二是工程一致性。团队里所有人用同一个模板生成项目，目录结构、代码风格、命名规范、环境变量管理方式全是一样的。这样带来的好处是，无论你接手同事的哪个项目，都能很快找到对应的文件位置，公共的封装也能跨项目复用。
第三是 CRUD 代码的自动化。这是 t3code 比较独特的地方。你在 Prisma schema 里定义好数据模型，执行一条生成命令，它会帮你生成对应的 tRPC router、zod 校验、数据库查询、前端列表页和表单页。这类代码的价值不在于多难写，而在于量大且重复，手工写很容易漏查询条件，模板生成就不存在这个问题。
第四是可扩展性。t3code 的模板本身是开放结构，团队可以维护自己私有的模板仓库，把公司内部的规范、公共组件、部署配置沉淀进去。比起官方脚手架那种“用一次就忘”的模式，t3code 更像团队内部的基础设施。
下面这个表可以更直观地看传统方式和 t3code 的差别：
| 环节 | 传统做法 | t3code 做法 |
|---|---|---|
| 项目初始化 | 手动安装并配置十多个包 | 一条命令生成完整工程 |
| 工程规范 | 人为约定，容易走样 | 模板统一，默认一致 |
| CRUD 接口 | 手工编写，容易遗漏边界 | schema 驱动，批量生成 |
| 数据库迁移 | 手动调整 schema 后逐个迁移 | Prisma migrate 集成 |
| 团队复用 | 靠文档和口头沟通 | 私有模板仓库沉淀 |
当然，t3code 不是万能的。它不是业务框架，不会帮你决定业务流程怎么走；也不是低代码平台，不会试图屏蔽掉代码本身。它的定位很明确：把工程化和重复劳动这部分做掉，业务逻辑仍然由开发者自己掌控。
2. 整体设计与技术选型思路
2.1 模块划分：CLI、渲染引擎、模板仓库
t3code 的整体架构不复杂，分三层。
最外层是 CLI，负责接收用户输入和参数解析。这一层我用的 Node.js 生态里比较成熟的库，命令解析用 commander，交互式问答用 prompts。之所以选这两个，是因为它们轻量、稳定、没有太多运行时依赖。CLI 层只做一件事：把用户在终端里做的选择收集起来，整理成一份配置对象，交给下一层。
中间层是核心引擎，负责把配置对象和模板文件组合起来，渲染出最终的项目文件。这里我用了一个叫 Eta 的 JavaScript 模板引擎。Eta 的语法很接近 EJS，但性能更好，体积也更小。模板文件会放在独立的 templates 目录里，每个文件里可以写<%= it.projectName %>这样的占位语法，渲染引擎会把这些变量替换成用户输入的实际值。
最内层是模板仓库。t3code 默认内置一套基于 T3 技术栈的模板，但你也可以把整套模板替换成自己维护的版本。模板仓库不只是源代码文件，还包括一个 manifest 文件，里面声明了模板版本、支持的 Node 版本、需要生成的目录结构、需要安装的依赖包等元信息。这样做的好处是，模板本身和 CLI 逻辑解耦，升级模板不需要改代码。
整个 t3code 项目本身是用 TypeScript 写的，打包工具用的 tsup。TypeScript 的首要价值是让 CLI 的配置对象结构可被类型约束，比如ProjectConfig里有哪些字段、哪些必填，写模板时也能得到类型提示。tsup 可以把 TypeScript 编译成 ESM 和 CJS 双格式的产物，兼容不同 Node 版本下用户的调用方式。
2.2 为什么采用模板渲染而不是通用代码生成器
这里有一个值得展开的设计决策：为什么用“模板渲染”而不是“AST 代码生成”来实现代码自动生成？
刚开始我也考虑过 AST 方案。AST 方案听起来更聪明：解析用户的 Prisma schema，抽象出语法树，然后直接操作语法树来生成 tRPC router 代码。它的好处是理论上可以精确控制代码结构，不受模板字符串的灵活性限制。但在实践里，我发现 AST 方案有三个明显问题。
第一是维护成本高。要生成多少种代码形态，就要写多少套 AST 操作逻辑。一个create接口要同时生成 zod input、Prisma 调用、tRPC procedure，这些逻辑如果用 AST 写，代码量会非常庞大。第二是调试困难，AST 生成的代码一旦有逻辑问题，你很难一眼看出“是哪个节点拼错了”。第三是用户改起来不直观，星标用户想给某个生成的接口增加一个字段，如果底层是 AST，他几乎没法手动介入，模板渲染至少还可以直接找到目标文件修改。
所以最终选择了模板渲染。CRUD 代码的好处是重复度高、结构固定，非常适合模板化。模板里可以写条件分支，比如用户选择了“内容表需要软删除”，模板里就渲染出带deletedAt的 Prisma 查询；用户没选，这个分支就不输出。生成出来的代码就是普通代码，开发者随时能改，这点非常重要。
另外，模板渲染还有一个工程上的好处：模板文件本身可以用 IDE 的高亮和校验。一个.eta后缀的模板文件，你可以按照 TypeScript 的语法去写，变量占位符是透明的，模板的错误会在渲染阶段提前暴露，而不是生成出来的代码编译时才报错。
给一个最简单的模板片段感受一下：
// src/server/api/routers/<%= it.modelName %>.ts import { z } from "zod"; import { createTRPCRouter, publicProcedure } from "~/server/api/trpc"; export const <%= it.modelName %>Router = createTRPCRouter({ list: publicProcedure.query(({ ctx }) => { return ctx.db.<%= it.modelName %>.findMany({ orderBy: { createdAt: "desc" } }); }), create: publicProcedure .input(z.object({ <% for (const field of it.fields) { %> <%= field.name %>: <%= field.zodType %>, <% } %> })) .mutation(({ ctx, input }) => { return ctx.db.<%= it.modelName %>.create({ data: input }); }), });你可以看到，模板里混着变量、循环、普通代码，渲染出来的结果就是一个可直接运行的 tRPC router。维护这样的模板，本质上和写普通代码没有区别，只是多了一套占位语法而已。
3. 核心实操：从零构建一个带权限管理的全栈模块
3.1 初始化项目：命令与参数
说再多设计思路，不如实际跑一遍。假设你现在要用 t3code 初始化一个全栈项目，环境要求是 Node.js 18 及以上，包管理器推荐 pnpm。我习惯用 pnpm，因为 Next.js 生态对 pnpm 的支持很成熟，安装速度和磁盘占用也更有优势。
执行下面这条命令：
npx t3code@latest create my-t3-app命令执行后，终端会出现一系列交互式问题。这里我列一下典型选项和我的建议：
| 选项 | 可选值 | 建议 |
|---|---|---|
| 包管理器 | pnpm / npm / yarn | 新项目建议 pnpm |
| 数据库 | SQLite / PostgreSQL / MySQL | 本地验证选 SQLite，生产选 PostgreSQL |
| 认证方式 | 无 / NextAuth / 自定义 JWT | 需要登录态的项目直接选 NextAuth |
| 组件库 | Tailwind 原生 / shadcn/ui | 我日常选 shadcn/ui，开发效率更高 |
| 是否生成 Docker 配置 | 是 / 否 | 会部署到服务器的建议选是 |
| 是否生成示例 CRUD | 是 / 否 | 首次使用选是，方便验证链路 |
选择完成后，t3code 会在当前目录创建一个my-t3-app目录。生成完成后的目录结构大概长这样：
my-t3-app/ ├── prisma/ │ ├── schema.prisma │ └── seed.ts ├── public/ ├── src/ │ ├── app/ │ │ ├── api/ │ │ │ └── trpc/ │ │ │ └── [trpc]/ │ │ │ └── route.ts │ │ ├── layout.tsx │ │ └── page.tsx │ ├── components/ │ ├── server/ │ │ ├── api/ │ │ │ ├── root.ts │ │ │ └── trpc.ts │ │ └── db.ts │ └── styles/ ├── .env.example ├── .eslintrc.cjs ├── .prettierrc.json ├── package.json ├── tsconfig.json └── Dockerfile生成完成后，还需要做两步：
cd my-t3-app pnpm install cp .env.example .env然后启动开发服务：
pnpm dev如果你生成的模板里带了示例 CRUD，打开浏览器访问http://localhost:3000，首页上应该能看到一个从数据库读取的示例列表。整个过程跑通后，说明脚手架本身没问题，接下来才是 t3code 真正开始发挥价值的时候。
3.2 用 schema 驱动生成 CRUD
假设现在需要一个文章模块，包含标题、正文、发布时间这几个字段。你先在prisma/schema.prisma里定义模型：
model Post { id String @id @default(cuid()) title String content String published Boolean @default(false) createdAt DateTime @default(now()) updatedAt DateTime @updatedAt }保存 schema 后，执行生成命令：
npx t3code@latest generate crud --schema prisma/schema.prisma --model Postt3code 会读取 schema，分析Post模型的字段和类型，然后生成一批文件。我这里以默认模板为例，生成的文件包括：
src/server/api/routers/post.ts src/app/(dashboard)/posts/page.tsx src/app/(dashboard)/posts/new/page.tsx src/app/(dashboard)/posts/[id]/edit/page.tsx src/components/post-form.tsx生成出来的 tRPC router 会包含list、getById、create、update、delete五个 procedure。每一个 procedure 都带对应的 zod 校验。比如生成出来的create接口，大致是这样的：
import { z } from "zod"; import { createTRPCRouter, publicProcedure } from "~/server/api/trpc"; const postCreateInput = z.object({ title: z.string().min(1, "标题不能为空"), content: z.string().min(1, "正文不能为空"), published: z.boolean().optional(), }); export const postRouter = createTRPCRouter({ list: publicProcedure.query(({ ctx }) => { return ctx.db.post.findMany({ orderBy: { createdAt: "desc" } }); }), getById: publicProcedure.input(z.object({ id: z.string() })).query(({ ctx, input }) => { return ctx.db.post.findUnique({ where: { id: input.id } }); }), create: publicProcedure.input(postCreateInput).mutation(({ ctx, input }) => { return ctx.db.post.create({ data: input }); }), update: publicProcedure .input(postCreateInput.extend({ id: z.string() })) .mutation(({ ctx, input }) => { const { id, ...data } = input; return ctx.db.post.update({ where: { id }, data }); }), delete: publicProcedure.input(z.object({ id: z.string() })).mutation(({ ctx, input }) => { return ctx.db.post.delete({ where: { id: input.id } }); }), });这里有几个细节值得注意。字段校验的规则会根据 Prisma 类型自动推断。比如title是必填字符串，生成的就必填；published有默认值，生成的就是可选字段。我在模板里还写了一条规则：所有字符串字段都检查最短长度，避免提交空字符串。如果团队有自己的校验习惯，比如手机号格式、邮箱格式，可以直接在模板里扩展 zod 校验规则。
生成完代码后，记得先跑一次数据库迁移，让表结构真实存在：
npx prisma migrate dev --name add_post_model npx prisma generate然后重启开发服务，前端页面上就能正常调用这些接口了。整个流程下来，从定义模型到页面可操作，大概只需要几分钟。
3.3 权限扩展与数据迁移
刚生成的 CRUD 是公开的，任何人调接口都能新增和删除文章。实际项目中肯定要加权限控制。这里正好演示一下，t3code 生成的代码不是“一次性代码”，你可以和平常一样继续往下写。
先在 schema 里加一个用户模型，并给 Post 加上 author 关联：
model User { id String @id @default(cuid()) email String @unique name String? posts Post[] } model Post { id String @id @default(cuid()) title String content String published Boolean @default(false) createdAt DateTime @default(now()) updatedAt DateTime @updatedAt authorId String author User @relation(fields: [authorId], references: [id]) }执行：
npx prisma migrate dev --name add_user_relation npx prisma generate现在把 tRPC 的create从 public 改成需要登录。假设你用的是 NextAuth，模板里自带了protectedProcedure，修改 router 里对应的调用即可：
create: protectedProcedure.input(postCreateInput).mutation(({ ctx, input }) => { return ctx.db.post.create({ data: { ...input, authorId: ctx.session.user.id }, }); }),还有个更细的权限场景：只允许作者本人或管理员更新、删除文章。这种逻辑不适合写在模板里，因为每个项目的权限模型不一样。我自己习惯在模板里提供一个叫assertCanModifyPost的辅助函数，生成时作为占位，真正的业务判断留给开发者手动实现。t3code 不会尝试替你决定权限规则，因为它不属于“重复劳动”，而属于业务逻辑。
3.4 一键构建 Docker 镜像并进行部署
项目开发完要部署，Docker 配置是团队里最容易出幺蛾子的环节。t3code 生成的 Dockerfile 是多阶段构建的，我这里贴一个简化后的版本：
# 依赖安装阶段 FROM node:20-alpine AS deps RUN corepack enable WORKDIR /app COPY package.json pnpm-lock.yaml ./ RUN pnpm fetch --store-dir /app/.pnpm-store # 构建阶段 FROM node:20-alpine AS build RUN corepack enable WORKDIR /app COPY --from=deps /app/node_modules ./node_modules COPY . . RUN pnpm install --offline --store-dir /app/.pnpm-store RUN pnpm prisma generate RUN pnpm build # 运行阶段 FROM node:20-alpine AS runner WORKDIR /app ENV NODE_ENV=production COPY --from=build /app/.next ./.next COPY --from=build /app/node_modules ./node_modules COPY --from=build /app/public ./public COPY --from=build /app/package.json ./package.json EXPOSE 3000 CMD ["pnpm", "start"]这里每一步都是有讲究的。基础镜像选的node:20-alpine，体积小，适合生产镜像。pnpm fetch会把依赖包下载到独立目录，构建阶段再用--offline安装，这样只要 package.json 没变，依赖层就会命中缓存，构建速度能快很多。需要注意的是，Next.js 的.next目录要在运行镜像里保留完整，否则静态资源会 404。
构建和部署命令也很简单：
docker build -t my-t3-app . docker run -d -p 3000:3000 --env-file .env my-t3-app部署后最好加一个健康检查。在 Dockerfile 里加：
HEALTHCHECK --interval=30s --timeout=5s --start-period=10s \ CMD node -e "fetch('http://localhost:3000/api/health').then(r=>{if(!r.ok)process.exit(1)}).catch(()=>process.exit(1))"健康检查不是为了好看，而是配合容器编排做自动重启和负载均衡。不然某个请求把 Node 进程打了死循环，服务没有正确退出，容器编排平台根本感知不到。
4. 实战中常见的问题与排查方法
4.1 Prisma 生成的类型和 tRPC 路由不同步
这个问题在我用 t3code 的过程中出现过好几次，而且最坑的是它不报错，只会在调用接口时返回奇怪的运行时错误。
典型场景是：你改了schema.prisma，又改了 tRPC router，重启开发服务后发现接口报TypeError: Cannot read properties of undefined (reading 'findMany')。原因通常是 Prisma Client 没有重新生成，或者生成的代码还停留在旧的 schema 版本上。ctx.db.post解析不到，是因为 Prisma Client 的运行时类型定义没有被更新。
排查思路很简单。先执行：
npx prisma generate然后重启 dev server。如果还不行，删掉node_modules/.prisma目录再重新 generate。这个目录是 Prisma 的缓存，旧版本偶尔会滞留。我通常在项目里配置一个 postinstall 脚本，每次安装依赖后自动执行prisma generate，可以从源头避免这个问题。
说到这里，还有一个容易混淆的点。t3code 生成的 CRUD 代码，引用的是ctx.db，这是我们在服务端统一封装过的 Prisma 实例。如果你在 Next.js 里同时用了旧版的全局 Prisma 客户端，很容易出现PrismaClient is not defined这种看起来很怪的错误。解决方式很简单：全项目只保留src/server/db.ts里那一个实例。如果是模板生成的旧项目，检查src/server/db.ts是否被重复修改过。
4.2 生成文件与手写代码冲突
t3code 不会傻乎乎地覆盖你已经改过的文件。它生成文件之前会先检查目标文件是否存在，存在就不动，而是打一条提示日志。这个设计是我踩了很多次坑后加进去的。
我第一次做自动化生成时，默认是直接覆盖同名文件。结果用户手动改过post-form.tsx里的校验逻辑，重新生成后改动全没了，还被 git 错当成一次大型重写。后来我学乖了：默认不覆盖已存在的文件，只有在你明确使用--force参数时才会覆盖。
日常使用建议是：生成完代码后，先跑git diff看一眼，再决定要不要覆盖。如果你确实想重新生成某个文件，先手动备份或依赖 git 的版本历史。这里我提供一个额外的小技巧，在项目根目录放一个.t3codeignore文件，把不希望被覆盖或者不希望生成的路径写进去，例如：
src/app/(dashboard)/posts/[id]/edit/page.tsx src/components/post-form.tsx这样即使执行了--force，这些文件也会被跳过，能有效保护手写的业务代码。
4.3 Windows 环境下的路径与命令差异
写 CLI 工具最头疼的就是跨平台。t3code 在 Windows 上踩过两个坑。
第一个坑是路径分隔符。Node.js 在 Windows 上返回的路径是C:\my-t3-app\src\server，模板引擎在拼绝对路径时如果直接用了字符串拼接，很容易出现C:\my-t3-app\src\server\src\server\api这种重复路径或者反斜杠和正斜杠混用的问题。我在所有涉及路径拼接的地方强制使用path.join方法，并保证模板内部引用路径统一使用正斜杠/。
第二个坑是 shell 脚本执行权限。默认模板里如果带了postinstall.sh或者entrypoint.sh，Windows 的 PowerShell 和 Git Bash 行为不一致，可能导致脚本无法执行。现在的解决办法是尽量减少 shell 脚本依赖，必要场景提供 Node.js 版本的替代方案。比如prisma generate这类操作，不要写成 shell 命令，直接用 Node 的execSync从 CLI 内部调用，跨平台行为会更一致。
如果你的团队里有人用 Windows，有人用 macOS，记得在项目文档里写清两个环境分别的启动命令差异，能减少很多不必要的沟通成本。
4.4 常见问题速查表
| 症状 | 可能原因 | 处理方式 |
|---|---|---|
全栈模板生成后pnpm dev报端口冲突 | 3000 端口被占用 | 换端口启动，或检查 3000 端口进程 |
访问/api/trpc显示空白或 404 | Next.js App Router 文件路径不对 | 检查route.ts是否在[trpc]目录下 |
Prisma 查询报Unknown argument | Prisma Client 版本与 schema 不匹配 | prisma generate并重启服务 |
tRPC 调用返回UNAUTHORIZED | session 未正确注入 | 检查 NextAuth 配置和ctx.session类型 |
| 生成的表单校验规则过严 | zod schema 推断不准确 | 手动调整模板中的 zod 规则，或者用自定义 validator |
| Docker 镜像构建时依赖缓存失效 | package.json 变化频繁 | 手动把 lock 文件与源码分离，减少依赖层触发 |
| 生成的文件找不到 | 模型名大小写或复数形式匹配不上 | 检查--model参数是否与 schema 中完全一致 |
5. 团队化使用与模板扩展
5.1 把公司规范沉淀成私有模板
t3code 默认内置的模板只是起点，真正让它发挥团队价值的是私有模板。
我在团队里是这样组织的：单独维护一个 git 仓库，里面放模板文件和一个t3code.template.json配置。这个配置里声明模板的版本号、支持的 Node 版本、默认的依赖列表，以及一些需要用户填空的变量，比如teamName、npmRegistry、internalComponentLib。然后 t3code 支持通过参数指定模板仓库：
npx t3code@latest create my-app --template git@github.com:company/t3code-template.git这个能力背后的逻辑是：团队规范不应该分散在项目里，而应该集中在一处，由工具把它注入到每个新项目里。比如公司统一用的日志中间件、请求 ID 注入、统一错误码格式，这些完全可以写进私有模板的createprocedure 里。这样所有新项目从一开始就带上规范的底座，而不是等项目上线之后再补。
不过要注意，私有模板的维护者需要有一定自律。模板改动会影响所有新项目，所以必须做测试。我自己的做法是准备一个空目录，每次改完模板就跑一遍t3code create，检查生成的项目能不能正常build。这一步看似麻烦，但能避免把坏模板同步给全团队。
5.2 升级模板时不毁掉存量项目
私有模板迭代后，存量项目怎么同步？这是团队化使用里最敏感的问题。
t3code 的默认策略是：模板只管新项目，不自动改动存量项目。原因很简单，存量项目里很可能有大量手写代码，强制同步模板等于强制他们放弃业务逻辑。所以模板升级要遵循两个原则。
第一个原则是向后兼容。增加新的生成文件类型时，不要移除旧的类型；新增依赖时，不要改动已有的 API 路径。第二个原则是提供 diff 工具。t3code 有一个scan命令，可以对比当前项目的代码和模板默认代码，输出差异清单。这样你能看到哪些文件是手写逻辑，哪些还保持着模板原样，根据差异决定要不要手动同步。
我实际推进存量项目升级时的流程是：先在测试分支执行t3code scan，生成差异报告，然后只同步那些确实没被人改过的文件，例如 ESLint 配置、Prettier 配置、Dockerfile 这类基础设施文件。业务代码保持不动，等下一次真实迭代时再按新模式改造。这个节奏比较稳，团队也不会因为升级工具而产生抵触情绪。
模板仓库本身也应该有清晰的版本管理。我建议每个模板版本打一个 git tag，并在t3code.template.json里写清 changelog。这样如果有人用旧模板开了项目，遇到问题还能定位到具体版本。
最后分享一个我自己的使用习惯。每次模板有重大变更，我一定会把新生成的项目完整跑一遍：初始化、构建、启动、调通示例 CRUD、部署到测试环境。这个流程看起来机械，但恰恰是最容易暴露问题的。t3code 到今天也不敢说能覆盖所有场景，但它确实把我从“每次开项目都从零搭一遍”的重复劳动里解放了出来。如果你也在维护团队脚手架，不妨从模板化开始，让工具替你做那些本来就不该手工反复做的事。
