t3code不是某个框架，也不是某个库，它是我最近小半年一直在用、也一直在维护的一个命令行工具。如果你和我一样，日常要在多个全栈项目之间切换，每次初始化项目都要翻文档找配置、手写重复的业务模块代码、提交之前还要自己肉眼看一遍有没有低级错误——那 t3code 就是冲着你这些场景来的。简单说，它是一个集项目初始化、业务代码生成、代码规范检查于一体的开发辅助工具，底层绑定的是 TypeScript 全栈技术栈。
这篇文章我打算把自己的实际使用流程、设计思路和踩过的坑完整捋一遍。不光讲 t3code 能做什么，更重要的是讲清楚它背后的取舍：为什么我选了这样的功能范围、什么样的团队适合引入它、哪些场景下它反而会碍事。如果你正准备在团队里推广类似的工具链，或者只是好奇一个“代码工具”应该怎么设计才算好用，这篇应该能给你一些参考。
1. 项目概述与设计思路
1.1 为什么需要 t3code：重复劳动才是真正的成本
先说个背景。我之前参与的几个项目，技术栈高度统一：TypeScript 打底，前端 React，后端 Node，数据库用 PostgreSQL，接口层走 tRPC。听起来很现代，但实际开发中有一个特别磨人的问题：每一次新建模块，都要重复做一堆没有技术含量但又不能出错的事情。
拿最基本的用户列表模块举例。你得先建数据库表结构、写 Zod schema 做校验、定义 tRPC router、写服务端查询逻辑、再在前端写 React hook 封装请求、最后还要把表单校验规则和后端保持一致。这一整套流程如果纯手工做，熟练的开发也要 40 到 50 分钟，而且很容易出那种特别隐蔽的 bug——比如前端传过去的字段名和后端 schema 不一致，或者 Zod 校验规则漏了一个字段，这类问题在编译期根本发现不了，非要到联调的时候才炸出来。
t3code 要解决的，就是这一整条链路上的重复劳动。它做的事情本质上很简单：把那些高度套路化、规则明确的编码工作做成可复用的模板，再通过命令行交互把模板实例化成你当前项目需要的代码。这个思路不新鲜，很多代码生成器都这么干，但 t3code 有几个不一样的地方：它生成的不是一堆散落的文件，而是和你的项目结构深度绑定的完整代码块，并且从生成的一开始就强制带上校验逻辑和类型定义。也就是说，用 t3code 生成一个模块，你用起来不是“拿到一堆需要自己填的模板”，而是“拿到一个可以直接跑起来的业务单元”。
我特别想强调一点：t3code 的目标不是让你不写代码，而是让你把精力集中在真正需要思考的业务逻辑上。像建表、写 CRUD、接路由、做校验这些活儿，不应该消耗你的脑力预算。
1.2 工具定位与技术选型：为什么是 TypeScript 全栈
给 t3code 做技术选型的时候，我其实纠结过一阵子。最早我想过用 Python 写一个独立脚本，跑在任意环境里，但很快就否掉了。原因很简单：t3code 的使用者几乎都是前端/全栈开发者，大家最熟悉的运行时就是 Node.js，如果引入一套 Python 环境，光环境配置就能劝退一半的人。所以最后定下来：Node.js CLI，npm 全局安装，使用者只需要一条命令就能跑起来。
语言层面当然是 TypeScript。t3code 本身还肩负着“输出规范 TypeScript 代码”的任务，自己都不用 TypeScript，说出去没说服力。而且 TypeScript 的类型系统能让模板代码的自动补全和静态检查做得更好——生成出来的代码可以直接被 IDE 识别，开发体验会顺滑很多。
这里我想多说一句架构上的取舍。t3code 的核心逻辑分成三层：模板层、渲染层、执行层，每一层的职责都很单一。
模板层存放的是所有模块模板，每个模板对应一类业务场景，比如module模板、page模板、api模板。渲染层负责把用户输入的关键信息填进模板占位符，同时处理条件分支——比如“你这个模块需不需要软删除？”如果不需要，生成的代码里就直接剔除对应逻辑。执行层则负责和项目文件系统打交道，它会检查文件是否已存在、依赖是否已安装、目录结构是否正确，保证生成结果能融入现有项目。
这套分层设计带来的直接好处是：新增一种模板不需要改工具的主逻辑，往模板目录里放一套新模板文件就行。我们团队后来内部加了好几个私有模板，都是这样扩展的，完全没动过主程序的代码。
2. 核心功能与实操要点
2.1 项目初始化：一条命令起跑
t3code 的第一个核心功能是项目初始化。它的定位和 create-next-app、create-t3-app 这类工具类似，但侧重点稍微不同——t3code 更强调“初始化完就能直接进入业务开发”，而不是只给你一个干净的空项目框架。
运行t3code init之后，它会进入一个交互式问答流程，大概会问这么几类问题：项目名、包管理器的偏好（npm、pnpm 还是 yarn）、是否需要数据库 ORM、是否内置 ESLint + Prettier 规范、是否需要内置登录注册逻辑（默认支持，用 NextAuth + 数据库 session 实现）。每个问题都有默认值，你直接回车也能跑完整个流程。
初始化结束之后，t3code 不光会帮你把项目骨架拉下来、装好依赖、初始化 git 仓库，还会额外生成一份project.config.json，里面记录了这次初始化的所有配置项。这个文件很关键，因为后续你再用 t3code 添加新模块的时候，工具会先读这个配置文件，自动沿用它记录的依赖版本和目录风格。也就是说，先后初始化两个项目，除非你刻意修改配置，否则它们生成代码的规范是完全一致的。
我特别推荐团队统一使用 t3code 做初始化，而不是个别成员手动创建项目再互相改。原因不复杂：手动初始化的项目，一百个人能整出一百种目录组织和配置风格，等代码合并到统一仓库的时候，光是统一格式就能折腾一两天。而 t3code 初始化出来的项目，目录结构、代码风格、配置项全是同一套标准，后面接手的同学不需要费力去猜“这个项目为什么这么组织”。
2.2 业务模块生成：不只是 CRUD 脚手架
t3code 的第二个核心功能是生成业务模块，这也是我日常用得最多的功能。表面上它是 CRUD 脚手架，但用久了你会发现，它生成的内容比大多数脚手架深一层。
执行t3code generate module user，工具会依次做这几件事：先创建数据库 Migrations 文件，再生成 Zod schema 和对应的 TypeScript 类型，然后生成 tRPC router，接着生成前端的 API 调用封装和基础页面组件，最后跑一遍类型检查和 lint。全流程大概几秒钟，之后你就得到一个可以立刻启动项目、在页面上看到真实数据和交互的模块。
这里面有几个实用细节值得展开说。
第一，字段类型映射是内置的。你在serializers里定义name: string、age: number、tags: string[]，t3code 会自动把它们映射成 PostgreSQL 对应的text、integer、text[]，同时生成匹配的 Zod schema 和表单组件类型。手工写这些映射不仅慢，而且容易出错，工具代劳之后，前后端类型不一致的概率大大降低。
第二，模板内置了常见业务规则的可选项。比如生成模块的时候，它会问你“是否需要分页”“是否需要软删除”“是否需要创建时间自动填充”。在传统脚本里实现这些功能往往要写一二十行代码，但在 t3code 里只是几个交互问题，回答完它就自动把对应的逻辑生成进去。
第三，生成代码遵循你项目已有的规范。它会读取项目根的 ESLint 配置和 Prettier 配置，生成出来的代码直接可以过 lint，不需要再手动调整格式。这点我想特别强调一下：很多生成器生成的代码格式和项目风格不一致，拿到手第一件事就是格式化，体验很差。t3code 在这一块是做过设计考量的，它不是硬套自己的模板，而是按项目的现有规范去输出代码。
2.3 规范检查与自动修复：提交前的守门员
t3code 第三个核心功能是代码规范检查，执行t3code check就能跑一个综合检查流程。它内部集合了 ESLint 检查、TypeScript 类型检查，以及一组 t3code 自己定义的项目结构规则检查——比如“有没有把 API 请求直接写在组件里”“有没有绕过 schema 手动构造查询参数”这类偏架构层面的问题。
这个检查命令我习惯在git commit之前执行。它的输出比裸跑 ESLint 友好很多，每个问题都会标注所在文件、行号、问题类型和修改建议，并且按严重程度分级。最关键的是，t3code check --fix可以自动修复大部分格式问题和一部分简单的逻辑问题，剩下的会列成清单交给开发者判断。
可能有人会问：不是已经有 ESLint 和 Prettier 吗，为什么还要 t3code 再做一遍？我的回答是：ESLint 管的是代码层面的规范，但管不了更上层的项目结构规范。比如说“所有页面组件必须放在src/features目录下，而不是随便乱放”，这类约定靠 ESLint 是表达不清的，而 t3code 可以把它们变成可校验的硬性规则。持续跑下来，团队的项目结构会非常稳定，评审代码的时候大家也不用再纠结“这个文件不该放这”这种问题。
3. 实操流程与案例演练
3.1 环境准备与安装
先把环境准备好。t3code 要求 Node.js 版本不低于 18，建议用 20 或更高，因为新版本对 ESM 的支持更好，运行体验也更稳定。npm 和 pnpm 都可以，但我个人更推荐 pnpm，磁盘占用小、安装速度快，t3code 自己也对 pnpm 做了专门的适配。
全局安装命令：
npm install -g t3code装完可以先跑一下版本号和帮助信息，确认安装成功：
t3code --version t3code --help如果你是在团队内部用，我建议让一个人安装并锁定版本，然后通过项目的package.json里的 devDependency 引入 t3code，而不是要求每个人都全局安装。这样版本唯一，不会出现“你那边是 1.2 我这里是 1.5，生成结果不一样”的问题。具体做法就是在项目里执行：
npm install -D t3code然后通过npx t3code调用，工具会自动使用项目本地版本。
3.2 从零初始化一个全栈项目
下面我们完整实操一遍。先建一个工作目录，执行初始化命令：
mkdir myapp cd myapp t3code init交互过程大概长这样（注意，这只是示例，具体选项以你实际使用的版本为准）：
? 请输入项目名称: myapp ? 选择包管理器: pnpm ? 是否启用数据库 ORM? (推荐) (Y/n) y ? 是否内置 ESLint + Prettier 规范? (Y/n) y ? 是否生成登录注册模块? (Y/n) y回答完之后，t3code 会开始拉取模板项目、安装依赖、初始化 git 仓库。整个流程大概两到三分钟，取决于网络速度。完成后应该是这样的目录结构：
myapp/ ├── prisma/ │ └── schema.prisma ├── src/ │ ├── features/ │ │ └── auth/ │ ├── server/ │ │ ├── api/ │ │ └── db.ts │ └── app/ ├── project.config.json ├── package.json └── tsconfig.json这一步完成后，直接执行pnpm dev就能启动项目。注意我第一次跑的时候还特意检查了一下project.config.json里记录的包管理器是不是 pnpm，确认无误后才继续。因为如果配置文件里写的是 npm，后续生成的代码在安装依赖时会去生成package-lock.json，和已有的pnpm-lock.yaml冲突，这个坑后面还会细说。
3.3 生成一个带分页和搜索的用户模块
项目初始化完成后，我们试着生成一个相对复杂的模块。目标：商品（product）模块，需要支持分页、搜索、按状态筛选。
执行：
t3code generate module product交互问答：
? 模块名称: product ? 是否启用分页? (Y/n) y ? 是否启用搜索? (Y/n) y ? 是否启用软删除? (Y/n) n ? 是否启用状态字段? (Y/n) y ? 需要哪些字段? name, description, price, status回答完成后，t3code 会做以下几件事（观察终端日志能看到具体过程）：
- 往
schema.prisma里添加Product模型，包含分页所需的游标字段、状态枚举、普通业务字段。 - 在
src/features/product目录下创建完整的模块代码，包括 schema、router、service、types 和 API 封装。 - 自动生成一个基础的列表页面组件（如果你在初始化时选择了包含前端页面模板）。
- 执行
prisma migrate dev生成迁移文件。
完成后我强烈建议先看一眼生成的router.ts，因为你会有两个非常直观的感受：一是代码规范程度高，函数注释、返回类型、错误处理都是按团队约定写好的，符合项目风格；二是类型定义闭环，前端拿到的数据类型就是后端 schema 推导出来的类型，不需要手动维护一套 interface。
这里我想提醒一个细节：生成模块后，别直接删掉src/features/product/types.ts里的内容然后手写一套自己的类型。t3code 生成的类型是从 Zod schema 自动推导的，手工改完可能和实际接口对不上，这等于放弃了工具最核心的价值。
3.4 提交前的综合检查与修复
模块生成完，一般还会改一些自己需要的逻辑。改完之后提交前，执行：
t3code check它会列出检查项、通过数量和问题数量。如果有问题，可以执行：
t3code check --fix自动修复能解决的它会直接改掉，比如引号风格、尾分号这些格式问题；它会保留的，是那些需要你做决策的问题，比如某个函数缺少返回类型标注、某个组件内直接调用了 API 请求等。这类问题它会给出文件路径和建议，逐个改就行。
如果有条件，我建议把t3code check接入 CI 流程，而不是只靠本地自觉。用 GitHub Actions 的话，可以在工作流里加一步npx t3code check --ci，让它在 Pull Request 阶段自动执行。我们的经验是：引入这个步骤之后，评审阶段关于“低级错误”的评论量显著下降，大家能把时间花在讨论业务逻辑上。
4. 常见问题与排查技巧实录
4.1 初始化报错：依赖安装超时
使用 t3code 过程中遇到最多的问题，集中在依赖安装阶段。有同事反馈过t3code init走到依赖安装时卡住，最后报网络错误。排查下来一般有两种原因：一是 npm registry 没有配置到国内镜像源，网络请求都打到了国外节点；二是 pnpm 的全局存储路径权限不足。
解决办法不复杂。先确认 registry 配置：
npm config get registry如果是默认地址，改成镜像源：
npm config set registry https://registry.npmmirror.com注意，改完之后重新执行t3code init之前，建议先手动删掉那个生成了一半的项目目录。因为 t3code 初始化时如果检测到目录下已有package.json，会认为项目已存在，然后跳过拉取模板的步骤，但依赖安装又会失败，状态会变得很奇怪。这是我自己实测踩过的坑，删掉重来最省心。
4.2 模板生成的代码和自己手写的风格有冲突
这个问题很多人会问：t3code 生成代码之后，我又自己加了一个文件，结果新文件和生成文件的风格对不上，怎么办？还有更头疼的：我改了project.config.json里某个选项，重新生成模块，结果同一个模块生成了两遍，新代码覆盖了旧代码，我之前手改的地方全没了。
先说风格冲突。t3code 生成的代码遵循的是项目里的 ESLint/Prettier 配置，你手写的代码如果遵循了同样的配置，理论上风格应该是一致的。如果出现冲突，先检查你手写的文件有没有被 ESLint 忽略，或者有没有在文件顶部加上// eslint-disable之类的注释。
再说覆盖问题。这个真的需要重视：t3code 在生成模块时默认不会覆盖已存在的文件，会直接报错提示“文件已存在”。所以重复生成一般不会搞丢手写代码。如果实在必须重新生成，可以手动删掉旧模块目录之后再做，不要试图在同一个目录上暴力重新跑生成命令。
提供一个排查技巧：每次生成模块之前，先执行git status确认工作区是干净的。万一生成结果不对，可以直接git checkout .回滚。养成这个习惯之后，我再也没因为实验性的生成操作弄丢过代码。
4.3 schema 更新后前端类型没跟上
t3code 的一大卖点是“类型自动同步”，但偶尔也会出现前端拿到的类型还是老版本的情况。这类问题绝大多数不是 t3code 本身的 bug，而是因为 tRPC 的类型推导是建立在 TypeScript 编译输出上的，你得确保后端代码的类型变更被重新编译，并且前端重新运行了类型检查。
我的处理流程是三步：
t3code check --fix pnpm dev第一步先跑检查，第二步重新启动开发服务，让 tRPC 重新生成类型。如果还不行，就检查一下是否有独立的类型生成命令需要手动触发。t3code 提供了一个t3code sync:types命令来强制同步全项目类型，这个命令在 CI 里也可以作为保险步骤接入。
4.4 团队协作时版本不一致的问题
最后说一个团队协作层面的高频坑。如果团队里有人用 t3code 1.2，有人用 1.5，两个人生成的模块结构可能不一样，合并代码的时候会有很多无谓的冲突。这个问题在工具类项目里特别普遍，解决方案就是我前面说过的：用项目的 devDependencies 固定 t3code 版本。
具体做法：
{ "devDependencies": { "t3code": "1.5.0" } }注意是精确版本号，不是^1.5.0。如果用了^，npm install可能装到 1.6，又会出现不一致。团队内部可以约定统一提交package-lock.json，这样所有人都用完全相同的版本。
另外，如果你们的项目已经不用 t3code 了，也建议在 README 里说明清楚，避免后面接手的新人看到配置后觉得有义务继续使用 t3code 维护代码。工具是服务业务的，项目不需要它了就不应该硬留着。
5. 一些实用心得与后续扩展方向
先说一个我个人的体会。t3code 这类工具，最大的价值其实不在于“少写代码”，而在于它让团队的代码规范从“靠人自觉”变成了“系统保证”。以前评审代码，总要花时间在“这里类型没写”“这个校验少了字段”之类的细节上，现在 t3code 自动把这些问题挡在提交之前，评审自然就快起来了。
我还想分享一个小技巧：如果你用了 VS Code，可以把 t3code 的命令绑定成快捷键。我自己把t3code check --fix绑定成了Alt+S，写完代码顺手按一下，格式化、类型检查、结构规则检查一次跑完，比切到终端敲命令省事很多。这个改动看起来小，但实际使用频率很高，长期下来对效率提升很明显。
t3code 后续还能怎么扩展？我目前有一个计划是做一个 VS Code 插件，把模块生成的交互做成可视化表单。理由也很简单：不是所有人都习惯命令行交互，可视化表单能让团队的初级成员更快上手，从而减少指导成本。如果你在用的过程中也想过什么好用的扩展方向，我建议先在自己项目里试试，用顺手了再贡献到公共仓库。
还有一点想提醒大家：自己维护工具，很容易陷入一种“工具化思维”——什么需求都想做成模板，什么逻辑都想抽出来复用。但代码生成这种工具，模板一旦做得过度抽象，生成的代码反而可读性差。我们定的原则很朴素：一个模板至少要有三个真实业务场景在使用，它才配留下来；否则就老实写手写代码。这样能让工具保持在一个足够精简、足够实用的状态。