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 CLInpm 全局安装使用者只需要一条命令就能跑起来。语言层面当然是 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绑定成了AltS写完代码顺手按一下格式化、类型检查、结构规则检查一次跑完比切到终端敲命令省事很多。这个改动看起来小但实际使用频率很高长期下来对效率提升很明显。t3code 后续还能怎么扩展我目前有一个计划是做一个 VS Code 插件把模块生成的交互做成可视化表单。理由也很简单不是所有人都习惯命令行交互可视化表单能让团队的初级成员更快上手从而减少指导成本。如果你在用的过程中也想过什么好用的扩展方向我建议先在自己项目里试试用顺手了再贡献到公共仓库。还有一点想提醒大家自己维护工具很容易陷入一种“工具化思维”——什么需求都想做成模板什么逻辑都想抽出来复用。但代码生成这种工具模板一旦做得过度抽象生成的代码反而可读性差。我们定的原则很朴素一个模板至少要有三个真实业务场景在使用它才配留下来否则就老实写手写代码。这样能让工具保持在一个足够精简、足够实用的状态。 
长河君 · 2026/10/28 23:24:21 · 阅读 1.2k 用t3code统一TypeScript全栈项目的初始化、代码生成与规范检查
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 CLInpm 全局安装使用者只需要一条命令就能跑起来。语言层面当然是 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绑定成了AltS写完代码顺手按一下格式化、类型检查、结构规则检查一次跑完比切到终端敲命令省事很多。这个改动看起来小但实际使用频率很高长期下来对效率提升很明显。t3code 后续还能怎么扩展我目前有一个计划是做一个 VS Code 插件把模块生成的交互做成可视化表单。理由也很简单不是所有人都习惯命令行交互可视化表单能让团队的初级成员更快上手从而减少指导成本。如果你在用的过程中也想过什么好用的扩展方向我建议先在自己项目里试试用顺手了再贡献到公共仓库。还有一点想提醒大家自己维护工具很容易陷入一种“工具化思维”——什么需求都想做成模板什么逻辑都想抽出来复用。但代码生成这种工具模板一旦做得过度抽象生成的代码反而可读性差。我们定的原则很朴素一个模板至少要有三个真实业务场景在使用它才配留下来否则就老实写手写代码。这样能让工具保持在一个足够精简、足够实用的状态。