TypeScript全栈开发脚手架t3code：Monorepo与代码生成实战

从第一次试用 t3code 到现在，我在好几个中大型项目里都把它用成了起手式。简单说，t3code 是一套以 TypeScript 全栈开发为目标的项目脚手架与代码生成工具，它解决的问题非常具体：新项目怎么在十分钟内跑起来、前后端类型怎么同步不撕裂、团队规范怎么从口头约定变成强制执行。这篇文章我会把 t3code 的设计思路、核心模块、完整实操流程和踩坑记录都摊开讲，适合正在搭中后台系统、微前端拆分或内部工具链的团队参考，也适合一个人写全栈但厌倦了重复配置的开发者拿来直接抄作业。

1. 项目定位与核心设计思路

1.1 新项目启动为什么这么费劲

我参与的不少项目都存在一个隐形成本：每次新开一个仓库，光是把基础设施铺好就能耗掉一两天。路由要配吧、状态管理要选型吧、接口层要封装吧、ESLint 和 Prettier 要统一吧、CI 要写吧，这些活儿本身没有技术含量，但每一次做都像把上次调的参再调一遍，而且不同人调出来的版本还不一样。

t3code 本质上就是把这一整套流程固化成 CLI 命令和模板仓库。它不是一个框架，不规定你必须用什么 UI 库、什么 ORM，它只搭建好一个合理的骨架，把类型安全、代码生成、规范检查这些跨项目通用的部分沉淀下来。我自己的定位是：它不是又一个全家桶，而是一个“半成品工程”，你拿到手之后只需要关注业务本身。

1.2 为什么不自接用现成的 Create 工具

有人会问，社区已经有 create-next-app、create-t3-app 这样的成熟工具，为什么还要自己造轮子。我的回答是：社区工具解决的是从零到一，但解决不了从一到 N。create-t3-app 出来的是一个单包应用，对于团队开发、多应用、公共包复用、数据库模型变更自动生成类型这些场景，它给不了太多帮助。

t3code 的差异化在于三件事：第一是 Monorepo 支持天然友好，初始化出来的就是 pnpm workspace + Turborepo 结构，应用、共享包、组件库从一开始就分清楚；第二是内置了代码生成管线，数据模型定了之后，zod 校验器、数据库类型、API 客户端模型可以一次性生成出来，不用手写；第三是规范化从生成那一刻就生效，新项目拿到的已经是统一的代码风格和提交规范，不存在“先跑起来、规范以后补”这种隐患。

1.3 设计边界：做什么与不做什么

t3code 目前明确不做的有这几块：不绑定具体数据库，你可以选 PostgreSQL、MySQL 或 SQLite，生成器通过适配器接入；不绑定 React 或 Vue，当前的模板默认是 React + Next.js，但 app 目录下的 runtime 层是独立封装的；不做运行时框架，生成的代码就是普通函数和类型，没有黑魔法，出了问题可以直接读源码调试。

这种边界的价值在于降低了团队的迁移成本。你用 t3code 初始化了一个项目，如果哪天觉得不好用，生成出来的代码仍然是可以直接继续维护的标准 TS 代码，不会被锁死在某个抽象层里。

2. 核心模块详解：t3code 里到底装了什么

2.1 Monorepo 骨架与工作流编排

t3code 初始化的目录结构是一个典型的 Turborepo 工程，主包和子包分开管理。我在实际使用中最常用的是 apps/web、apps/server 和 packages/ui 三层，中间夹着 packages/db 和 packages/validators。

monorepo-root/ apps/ web/ # Next.js 前端 server/ # Node.js API 服务（Express/Fastify） packages/ ui/ # 共享组件库（React + Tailwind） db/ # 数据库 schema 与迁移脚本 validators/ # zod 校验模型（前后端共用） config/ # ESLint / TS 配置的统一出口 pnpm-workspace.yaml turbo.json

这套结构的好处我之前体会得特别深。以前前端和后端的类型各管各的，后端改了字段，前端经常要等接口文档更新了才知道，现在通过 pnpm workspace 直接引用 packages/validators，接口响应类型变了编译就直接报错，根本留不到联调阶段。

Turbo 在这里承担的是任务编排职责。t3code 生成的项目里预设了几个 turbo 任务：dev会并行跑 web 和 server，build会按依赖拓扑自动排序，lint和test会在提交前通过 husky 自动执行。实战建议：turbo.json 里的 dependsOn 配置要按自己的包依赖关系调一下，否则会出现新加的包没有构建就被引用的情况。

2.2 类型安全的三层防线

t3code 对类型安全的重视程度是贯穿到代码生成器里的，我把它总结为三层防线。

第一层是数据模型层。你在 packages/db 里定义好数据库表结构，无论是 Kysely 的 schema 还是 Prisma 的 model，t3code 的生成命令会解析这个 schema，自动生成 TypeScript 类型和 zod 校验器，这两个产物就是整个系统的事实来源。我实际验证过，生成出来的类型能覆盖 nullable、default、enum 这些基本场景，遇到复杂联表是用 DTO 手动补充，生成器不会越俎代庖，这点很克制。

第二层是 API 契约层。前端发起请求时会通过一个类型化的 client 函数，比如api.product.list(params)，它的入参和返回值都来自 packages/validators 里的类型，路由出参和前端入参直接由编译器把关。这一层之所以可靠，是因为它不依赖运行时反射，纯粹是类型层面的约束。

第三层是环境变量与配置层。t3code 生成的 config.ts 会读取环境变量，并用 zod 做运行时解析，一旦环境变量缺失或类型不对，服务启动阶段就会被 zod 拦截。我在多个项目里都靠这个提前拦下了因为少配一个DATABASE_URL导致的线上事故。

2.3 代码生成管线：一次定义，多处生效

代码生成是 t3code 最核心的功能，它解决的不只是重复劳动，而是重复劳动中的“不一致”问题。整个管线以 schema 为中心，跑一次命令，生成器会做以下几件事。

首先生成数据库迁移文件与类型模型。以 Prisma 为例，t3code 会执行prisma generate和prisma migrate，并把生成的 types 统一汇入 packages/validators。然后生成 zod 校验器，与数据库模型一一对应，前后端可以直接引用。最后生成 API 客户端路由函数字典，后端定义好路由后，前端 client 会自动获得带类型声明的调用入口。

实际操作中，t3code 的 watch 模式很有用：命令行工具会在 schema 文件变化后自动触发轻量生成，而不是每次手动跑全量命令。注意：自动生成和手动修改不要同时进行，建议 schema 目录是唯一手写区域，生成的代码一律只读，否则小版本升级时 diff 会非常痛苦。

2.4 质量防护与提交规范

规范这种东西，靠人自觉基本等于没有，必须靠工具强制。t3code 里内置的规范体系分四层。第一层是 ESLint 配置，flat config 形式，集成了 TypeScript strict 规则、import 排序规则、React 推荐规则；第二层是 Prettier 统一格式化；第三层是 husky + lint-staged，在 commit 前只对暂存文件做检查，速度很快，observability 的强依赖是这些工具本身不能太慢；第四层是 commitlint，commit message 强制 conventional 格式，保证 changelog 生成和版本号管理顺畅。

这套体系我用了大半年，最大的感受是 PR review 的时间省下了很多，因为代码风格问题全部前置解决了，review 只需要关注逻辑本身。如果团队之前没有用过 strict TS 模式，会有几天适应期，但建议千万不要为了迁就把 strict 关掉，这个门一旦打开就关不回去了。

3. 实操全记录：从零跑通 t3code

3.1 环境准备与安装

t3code 对运行环境的要求很简单：Node.js 18+ 和 pnpm 8+。我推荐用 pnpm 作为包管理器，因为 workspace 支持更彻底，磁盘占用也更低。安装 t3code 本身可以通过 pnpm 直接拉起，或者作为 devDependency 固定在工程里。

# 全局安装 CLI 工具 pnpm add -g t3code # 或者使用 npx 临时拉取 npx t3code --help

初始化新项目时建议先确认目标目录为空，t3code 不会让你在一个已有内容的目录里跑 init，这是防呆设计，避免模板覆盖掉已有仓库。如果你是团队使用，我强烈建议把 t3code 固定在 package.json 的 devDependencies 里，版本锁定能避免不同成员之间模板不一致的问题。

3.2 初始化项目与交互式配置

运行t3code init后，CLI 会进入交互式问答，这一步相当于把项目的基本偏好录入进去。会问到下面的这些配置项：应用类型是纯前端、纯后端还是全栈；前端框架默认 Next.js；后端框架可选 Express、Fastify 或 Hono；UI 层是否启用 Tailwind；数据库选择 PostgreSQL、MySQL 或 SQLite；是否需要 docker-compose 文件。

我建议第一次使用选默认值跑通，之后再逐步自定义。比如我先选了全栈 + Next.js + Fastify + PostgreSQL，生成出来的代码能直接pnpm dev跑起来，前后端同时监听 3000 和 4000 端口。这一步体验很关键，如果初始化完第一步就报错，用户很容易放弃，t3code 在这块的默认路径打磨得比较顺。

pnpm create t3code@latest my-app cd my-app pnpm install pnpm dev

启动成功后，浏览器访问 3000 端口能看到一个简单的状态页，上面写着前后端连接状态、数据库连接状态、生成器状态，这几项绿灯说明骨架本身没问题，可以往里填业务了。这个状态页也是一个很好的示例代码，新成员入职时先跑一遍这个流程，对系统全貌会有直觉。

3.3 用代码生成器接入第一个业务模块

现在以一个“商品管理”模块为例，完整走一遍生成流程。首先在 packages/db 的 schema 文件里定义模型，然后运行生成命令。

# 定义好 schema 后执行生成 pnpm t3code generate --watch=false

生成器会产出以下内容。数据库迁移 SQL 文件，通过 migration 命令执行后建表；TS 类型文件，表行数据的严格类型；zod 校验器，用于 API 入参校验；API 客户端函数，前端可以直接调用。

后端路由是这样写的：

import { z } from 'zod'; import { ProductCreateInput } from '@my-app/validators'; import { createProduct } from './product.service'; export async function productRoutes(app) { app.post('/api/products', async (req, reply) => { const payload = ProductCreateInput.parse(req.body); const result = await createProduct(payload); return reply.code(201).send(result); }); }

前端调用时，类型是自动带出来的，IDE 会有完整的补全和提示：

import { api } from '@my-app/api-client'; const products = await api.product.list({ page: 1, pageSize: 20 }); console.log(products.items.map((p) => p.name).join(', '));

整个过程不需要手动维护接口 DTO，因为生成器已经把类型铺到前后端两侧了。对我这种以前经常改字段改到前后端不一致的人，这种体验就是回归到“改一处、全生效”的原始诉求上。

3.4 自定义模板：把团队标准固化起来

t3code 比较有长期价值的是模板自定义能力。工具会在~/.t3code/templates/下放置默认模板，你可以把这些文件复制到团队仓库里修改，然后在 init 时通过--template指向自定义模板路径。

我实际整理过一个团队模板，做了几件默认模板没有的事：加了公司统一的 HTML 标题后缀和 meta 配置；内置了内部的请求错误码映射表；加入了后台管理系统的初始布局（侧边栏、顶栏、权限路由示例）；增加了单元测试的最小示例文件。

自定义模板有一点要注意：t3code 在做文件渲染时支持简单的{{ variable }}占位符，比如项目名、包名、作者邮箱，还有条件渲染{{#if withDatabase}}，这些变量在 init 交互阶段会赋值。模板改造后可以在本地起一个临时目录验证渲染结果，确认无误再提交团队仓库。

4. 上线与维护中的高频问题排查

4.1 Turborepo 与 pnpm workspace 的依赖坑

新项目初始化后最容易遇到的坑是本地一切正常，但 CI 上 build 报错Could not find the module @my-app/validators。这种问题九成出在 package 版本还没有 publish 或者 workspace 软链没有生效。排查时先检查pnpm-workspace.yaml里的packages是否包含 packages 目录，然后跑pnpm install后确认node_modules/@my-app/validators是否是一个符号链接。CI 环境则要看 npm registry 配置，私有包还需要配好.npmrc的 scope 指向。

4.2 数据库模型变更后类型不同步

开发过程中经常改 schema，但生成的类型没跟着更新，就会出现前端明明引用了新字段，编译也没报错，运行时却是 undefined 的情况。原因是 t3code 的 watch 模式没启动。建议在开发工作流里明确约定：改完 schema 后顺手执行pnpm t3code generate，或者恒常开启 watch 模式。另外，在 CI 里可以加一步“模型漂移检查”，跑生成器后检查 git diff 是否为空，不为空就说明有人手改了生成的代码，直接让构建失败。

4.3 生成物一致性对不上手写代码

我踩过生成器把 zod 版本升级后，生成代码中的某些校验方法失效，但手写部分还在用旧 API 的坑。这类升级问题统一处理方式是把生成器、模板版本和项目模板版本三者作为一个整体发布和升级，不要单独升级其中一个。t3code 的 CLI 里提供了t3code doctor命令，会检查模板版本、生成器版本、zod 版本、TS 版本之间的兼容矩阵，有问题会直接列出来。

4.4 团队不愿执行规范怎么办

哪怕工具都装好了，团队入坑时还是会有人提交乱七八糟的 commit 或者跳过 lint。我的经验是几个措施一起上：第一，commit-msg 钩子上 commitlint 一定要强制，不允许--no-verify；第二，CI 上跑pnpm lint && pnpm typecheck，作为合并的硬性门槛；第三，把这些检查从“惩罚项”变成“提示项”，比如 lint 规则里把有自动修复能力的都标成 warn，降低改动成本，但 error 仍然强制不通过。

4.5 高频问题速查表

5. 一些真实心得与后续可以怎么扩展

5.1 用得越久，越觉得“生成”比“配置”更可靠

我自己用过几种主流的脚手架，t3code 用下来最大的差异是它的“代码生成”思维。普通的配置型工具是给你一个框架，剩下全靠手写；t3code 则是把重复的逻辑收拢成一个可执行的步骤，每次输出都是完整且可读的文件。这种做法的好处，除了效率，还有维护性：生成的代码是真实存在的，调试时可以直接打开看，不需要通过魔法层去猜。如果你在团队里推行，建议从一个小模块的单表 CRUD 开始试用，让成员体验“定义模型、跑一个命令、前后端直接联调完事”的流程，比讲什么大道理都有效。

5.2 后续扩展的几个方向

如果你已经把 t3code 用得比较熟了，可以往这几个方向继续拓展：第一，接入 OpenAPI 规范导出，让外部团队也能通过标准方式消费你生成的接口定义；第二，为移动端或小程序端加一个轻量客户端生成器，共用同一套 validators，移动端和后端也能类型同源；第三，把模板做成 monorepo 内的一个包，发布机制做成带 changelog 的版本管理，这样跨项目升级模板时能力和风险都可控。我在实际做的时候还加了一个小插件机制，自定义本地命令去读取业务配置，生成更贴近业务场景的代码，但核心思路是一样的：把“唯一手写区”的 schema 尽可能做厚，别让同一份逻辑在项目里出现多个来源。

5.3 最后一个避坑工具：先跑 doctor 再提版本

最后分享一个小习惯。每次升级 t3code 或者大改模板之前，我都会先跑一遍t3code doctor，再跑一遍模板项目的generation全链路测试。这个流程看起来很基础，但真的帮我挡掉过不少次因为依赖矩阵不匹配导致的批量生成失败。如果你的团队也打算批量铺开这套工具，把这个检查当成升级的前置门禁，能省下不少排查时间。