1. t3code 是什么？它解决的开发痛点

先说结论：t3code 是一个围绕现代 Web 全栈开发场景设计的轻量级命令行辅助工具集。你可能听说过 t3 技术栈——TypeScript、Tailwind CSS、tRPC、Next.js 那套组合拳，而 t3code 这个项目，相当于是围绕这类开发流程做了一层"脚手架 + 代码生成 + 工程规范"的整合工具。

我第一次接触到 t3code 的时候，正好在折腾一个中小型全栈项目。团队里有人习惯先写 API 再写页面，有人喜欢先定义 schema 再补路由，结果就是代码风格越写越散，类型定义来回拷贝，git 提交信息也五花八门。t3code 吸引我的地方在于，它不要求你改变整套技术选型，而是把开发流程里重复性最高的部分——路由生成、类型对接、数据库 schema 同步、组件骨架——变成几条命令，跑完直接产出可用代码。对于"一个人维护两三个项目"的独立开发者或小团队来说，这种工具的价值不是炫技，而是把每天浪费在机械操作上的时间省出来

需要先说明一点：t3code 并不是某个数据库官方出的标准工具，也不等于 Next.js 项目初始化器。它定位在"项目初始化之后、业务开发之前"和"业务开发过程中"这两个阶段。你用它初始化一个带类型安全的全栈项目，之后每次新增数据模型、 API 路由或页面，都可以调用它生成配套代码。换句话说，它是你工程化流程里的"半自动档"，而不是"一键全自动档"。

对我个人来说，最实用的部分不是它的初始化模板，而是它在"类型一致性"上的约束。前后端共用一个 schema 文件，改一处，联动的类型定义和校验逻辑都能重新生成——这一点在做 tRPC 这类端到端类型安全的项目时，体感特别明显。

2. 安装与首次启动：最容易踩的坑

安装 t3code 的常规方式是 npm 全局安装：

npm install -g t3code

装完之后跑t3code --version验证。如果你网络环境正常，这一步通常不会出问题。真正容易踩坑的是后面两步：初始化项目时因 Node 版本不匹配报错，以及首次运行命令时缺少配置文件导致的中断。

2.1 Node 版本选择：别用太老也不要太新

t3code 的实现依赖现代 JavaScript 语法和一些 Native 模块，Node 版本太低会直接报语法错误，版本太高（比如刚发布的奇数版本）又有可能与某些依赖的预编译二进制不兼容。

我建议使用 Node.js 18 LTS 或 20 LTS，这两个版本是当前生态里兼容性最稳的区间。可以用 nvm 管理版本，在项目根目录加一个.nvmrc文件：

echo "20" > .nvmrc

然后每次进入项目目录跑nvm use，避免"在我机器上明明是好的"这类尴尬。

2.2 初始化命令：不生成多余文件

t3code 提供了一条初始化命令，用于在当前目录生成基础工程结构：

t3code init

执行之后，它会询问几个问题，比如"项目名称""是否启用 Tailwind CSS""是否启用 tRPC""是否启用 ESlint/Prettier"等。这里有个经验：不要一上来就全选 yes。优先只选当前需要的，之后再通过t3code add追加。这样生成的配置文件干净，排查问题的时候干扰项也少。

初始化完成后，目录里多了t3code.config.ts（或t3code.config.js，取决于你选的模板）。这是整个工具的核心配置文件，后续所有生成命令都围绕它工作。它大概长这样：

// t3code.config.ts import { defineConfig } from 't3code' export default defineConfig({ schemaPath: './src/schema', routesDir: './src/pages/api', generateDir: './src/generated', database: { provider: 'sqlite', url: 'file:./dev.db', }, // 更多配置项见下文 })

2.3 首次启动失败排查

初始化之后直接跑t3code generate如果报错，十有八九是以下三个原因之一：

1. schema 目录不存在——工具不会自动创建深层目录，先手动建好src/schema再跑。
2. 配置文件语法错误——如果改了配置，自己先node --check t3code.config.ts或靠 IDE 的 TS 检查过一遍。
3. 生成的代码与现有目录中的文件冲突——如果目标目录已有同名文件，部分版本会直接退出而不是覆盖。

遇到第 3 种情况，别急着删文件，看看报错里有没有--force参数提示。我平时会加-f强制执行，但前提是本地的改动确认可以丢弃。

3. 核心功能拆解：三条命令覆盖日常开发主线

t3code 的命令不多，常用场景下真正高频的只有三条：generate、add、watch。

3.1 generate：从 schema 到类型与接口代码的一次性生成

这是 t3code 最重要的命令。它会读取配置文件里schemaPath指向的目录，解析里面的数据模型文件，然后向generateDir输出类型定义、校验逻辑和对应的服务端路由骨架。

举个例子，你在src/schema/user.ts里定义了一个用户模型：

// src/schema/user.ts import { z } from 'zod' export const UserSchema = z.object({ id: z.string().uuid(), name: z.string().min(1), email: z.string().email(), role: z.enum(['admin', 'editor', 'viewer']), createdAt: z.date(), }) export type User = z.infer<typeof UserSchema>

跑：

t3code generate

它会在src/generated下生成对应的 API 路由文件、前端类型定义文件和数据库操作封装。整个过程大概几秒钟。create、update、delete、list四个基础的 CRUD 操作都会生成，不用自己手写样板代码。

这里需要理解一个关键设计：schema 是唯一事实来源。你不需要在路由层再写一遍字段校验，也不需要在前端再定义一套类型。生成的内容都从这份 schema 推导而来，这能从根本上消灭"前端类型和后端类型不一致"的问题。

3.2 add：按需追加能力模块

generate是全量生成，add则是增量添加。比如项目开发到一半，需要加一个"评论"模块：

t3code add comment

它会自动创建一个符合你项目结构的、规范的评论模块雏形，包括 schema 文件、路由文件和基础 UI 组件占位。关键是这个新模块会和已有代码保持风格一致，命名规范、引用路径都与项目原有生成代码统一。

我一般用这种方式来管理"功能模块的增长"，避免每个新功能都重写一遍路由和类型定义。重构的时候也省事，删掉一个模块，只需要把对应 schema 文件删掉，再跑一次generate，所有引用它的生成文件也会一并被清理。

3.3 watch：改动即生成

开发过程中，每次改完 schema 就手动跑一次generate，非常影响节奏。t3code 提供了 watch 模式：

t3code watch

它会监听 schema 目录下的文件变化，修改保存后自动重新生成相关代码。这个模式在开发期特别推荐，体验接近于"写完类型直接能用"。但有个前提：生成代码的目录不能手动改。如果改了，下一次 watch 重新生成时变更就会被覆盖，容易产生"我改的代码怎么消失了"的困惑。

4. 实战场景：从零搭建一个带类型安全的博客后台

光说命令面面俱到容易飘，我拿一个比较典型的场景串一遍，你就知道 t3code 在真实项目里是怎么用的。假设我们要做一个极简的博客后台，有"文章"和"标签"两个核心实体。

4.1 准备数据模型

先定义两个 schema 模型。

文章模型：

// src/schema/post.ts import { z } from 'zod' export const PostSchema = z.object({ id: z.string().uuid(), title: z.string().min(1), slug: z.string().regex(/^[a-z0-9]+(?:-[a-z0-9]+)*$/), content: z.string().min(1), published: z.boolean().default(false), tags: z.array(z.string()), createdAt: z.date(), })

标签模型：

// src/schema/tag.ts import { z } from 'zod' export const TagSchema = z.object({ id: z.string().uuid(), name: z.string().min(1), slug: z.string().regex(/^[a-z0-9]+(?:-[a-z0-9]+)*$/), })

4.2 执行 generate

t3code generate

生成结束后，项目里会多出以下能力（以实际工具输出为准，大致方向是这样）：

• 基于 Zod 的类型定义：Post、Tag，前端可以直接 import 使用。
• 服务端路由：/api/posts、/api/posts/[id]、/api/tags、/api/tags/[id]等，支持标准的 GET/POST/PATCH/DELETE 操作。
• 数据库访问封装：使用 Prisma 或 Drizzle 风格的访问层，具体取决于你在配置文件里选的 provider。

等于说，最枯燥的路由样板和类型重复代码，一分钟内全部生成完。

4.3 在业务代码里使用生成产物

以 Next.js + tRPC 为例，生成之后你只需要专注写业务逻辑。比如创建文章的时候，把请求体交给生成的校验函数：

import { PostSchema } from '~/generated/schema' export const createPostHandler = async (input: unknown) => { const parsed = PostSchema.parse(input) // parsed 已经是类型安全且校验过的数据 return db.post.create({ data: parsed }) }

页面端也直接从生成目录里引类型：

import type { Post } from '~/generated/types' const post: Post = await fetcher('/api/posts/1')

整个过程下来，前后端代码中"靠人肉同步"的部分明显变少。我过去最头疼的事——改一个字段名，跨三个文件手工替换——从现在开始变成了"改 schema，保存，没了"。

4.4 与现有代码共存

如果你已经在用 tRPC + Prisma 的成熟项目，想引入 t3code，可以只把它用在"新增功能模块"上。不需要回填旧代码， t3code 的generateDir是可以指定到项目新目录的：

t3code add post --outDir ./src/features/post

这样生成代码就落在features目录，和已有pages目录互不干扰。等团队适应这套流程后，再把存量代码一步步迁移过来。

5. 配置文件逐项分析：不背参数，但要知道每个选项在管什么

很多人拿到配置文档就开始死记硬背，其实没必要。只要理解了每个配置项背后的作用域，用的时候查一眼就够。

5.1 schemaPath 与 generateDir

这两个是"输入输出"路径。schemaPath告诉工具去哪里读数据模型，generateDir告诉工具把产物放哪里。

建议把 schema 放在项目根级共享目录，而不是放在后端目录里。因为 schema 本身是前后端共用的契约，放得太深反而不好引用。比如src/schema就是不错的约定。

5.2 routersDir / routesDir

这个配置项控制生成的路由文件位置。不同框架下，这个目录名的含义略有差异：

如果你用的是 tRPC，生成的路由文件不是 HTTP handler，而是 tRPC 的 router 片段，最后手动挂载到根 router 上。这是多个项目里最常见的混淆点，我在一开始也踩过，总以为生成完就能直接请求了。

5.3 database.provider 与 url

这里声明数据库类型和连接。t3code 支持 sqlite、postgresql、mysql 三种常见选项。注意：它不会替你建表，而是生成"数据库访问层"代码，具体的 migration 还需要依赖你选用的 ORM（比如 Prisma 或 Drizzle）来执行。

我目前的习惯是：provider选sqlite做原型开发，跑通后再把连接串换成 PostgreSQL 的 URL 并执行迁移。只要 schema 定义里没有用 SQLite 不支持的类型，一般都能顺利切换。

5.4 output.style

配置生成代码的代码风格。可选arrow和function，推荐function，因为服务端路由里 hoisting 问题更少。另外可以开启includeZod选项，让生成的代码里包含 zod 校验，方便在服务端入口直接调用。

export default defineConfig({ output: { style: 'function', includeZod: true, }, })

5.5 prettier / eslint 联动

t3code 生成出的代码本身是格式化的，但如果你的项目有独立的 Prettier 配置（比如自定义了 printWidth），建议在生成后跑一次npx prettier --write再提交，避免 CI 阶段格式检查报错。

6. 踩坑记录：版本冲突、生成目录污染和 schema 设计误区

工具再好用，坑也不少。下面这几类问题是社区和个人实践中最高频的，也算是我用得比较久攒下来的教训。

6.1 本地依赖与全局命令版本不一致

项目里如果同时存在t3code的本地依赖（package.json中声明）和全局安装的 t3code，可能出现本地版本和全局版本行为不一致的情况。最典型的是：全局是 1.2，项目里 lock 到 1.0，跑命令时用的是全局版本，生成结果的字段和本地类型对不上。

解决办法：项目内固定版本，用npm scripts调用。在package.json里加：

{ "scripts": { "gen": "t3code generate", "gen:watch": "t3code watch" } }

然后统一npm run gen，不要依赖全局命令。

6.2 生成目录被手动修改后引发的"幽灵差异"

有时你会在生成目录里直接改代码，图快。但下一次generate时， t3code 会基于 schema 重新生成，你的改动会被覆盖。如果没注意，就可能出现"明明改了文件却没生效"的情况。

我的建议是：把generateDir加入.gitignore之外的"人工禁区"，不要手动编辑该目录里的文件，顶多在代码 review 时查看。非要自定义某个生成文件，应该回到 schema 里增加配置项，或者写一个afterGenerate钩子来做后处理，而不是直接改产物。

6.3 schema 字段使用z.date()的小心机

如果你是 SQLite 数据库，z.date()生成的对应字段在存储层会被当成字符串处理。读出来的时候，ORM 通常会帮你转成Date对象，但如果你直接用 SQL 查询，返回的是字符串。写业务代码时，最好统一在 schema 层转换：

const safePostSchema = PostSchema.transform((data) => ({ ...data, createdAt: new Date(data.createdAt), }))

6.4 删字段不等于删干净

很多人删改 schema 里某个字段后，发现前端/服务端依旧报错。原因是生成的类型文件虽然更新了，但业务代码里可能还留着旧的引用。我建议删字段后全局搜一下旧字段名：

rg "oldFieldName" ./src

把所有残留引用清理干净，再跑类型检查npx tsc --noEmit。

6.5 watch 模式与 CI 环境冲突

在 CI 流水线里千万别跑t3code watch，它会一直挂起不退出，导致任务超时。正确做法是在 CI 里跑：

t3code generate --check

这个命令只做"生成并比对差异"的操作，如果发现当前代码与 schema 不一致，就报错退出，这样可以让 CI 承担"检测契约同步"的职责。

7. 为什么说 t3code 适合中小团队而非大团队

这个工具不是银弹，它的适用边界我觉得值得单独聊一次。

7.1 中小团队的"单一事实来源"需求强

在 2~5 人团队里，没有专职的 API 层维护者，大家对"类型定义到底以谁为准"常常没有统一认知。t3code 恰好把 schema 抬升为唯一事实来源，不管怎么写，最终都汇总到生成代码里。这种约束对大团队反而难以推行——因为大团队有各自的模块边界，一个全局 schema 牵扯太多协作。

7.2 架构演进初期的快速原型能力

t3code 适合在"架构还没完全定型"的阶段使用。比如你在比较 tRPC 和传统 REST 方案时，可以用 t3code 分别生成两套工程结构，对比代码量和维护成本，再决定走哪条路。它让你不需要先手工搭建一整套脚手架才能做技术验证。

7.3 不适合的场景

• 对已有大型代码库做全量迁移——历史包袱太多，生成代码反而会打破定制逻辑。
• 高度定制化的 API 设计——如果大量接口都不是 CRUD，而是复杂的按需聚合响应，强行套 schema 生成就是削足适履。
• 团队里没人愿意接受"生成代码不可改"的约束——如果大家都习惯手改产物，这套流程跑不起来。

8. 从 t3code 迁移到自维护生成器的思路

如果你的项目发展大了，或者 t3code 不能满足所有自定义需求，不用急着抛弃。更优雅的做法是参考它的 schema 约定，同样保持单一事实来源，但用自定义脚本生成自己的代码。

很多模板引擎（如plop、handlebars、ts-morph）都能帮你建立类似能力。以ts-morph为例，你可以在脚本里解析 schema 文件，动态生成类型和路由文件。t3code 本身就像一个"可读的参考实现"，理解它的核心流程后，你完全掌握自己项目的生成逻辑，也就不用担心被工具绑架。

如果有一天工具不再维护了，由于它的 schema 文件仍然是普通的 TypeScript + Zod，迁移成本就很低——你只是失去了代码生成器，但数据契约还在，完全可以自己写脚本续命。

9. 总结一点个人体会

我用这类代码生成工具的周期不算短了，最大的感触是：工具省下来的时间，远远不如"约束带来的认知一致性"有价值。t3code 让我从"每次都要想一遍路由怎么命名、校验写在哪"里解脱出来，把注意力留给真正的业务逻辑。

当然，你要接受它的一些脾气：生成目录不能手改，配置要按它的规则来，新版本升级要留神。但只要是 schema 驱动的开发方式，这些成本都是可控的。

如果你正在从零搭建一个全栈项目，或者手上正好有那种"数据类型不断变、接口改来改去"的中型项目，花一个下午把 t3code 跑通，投入产出比还算划算。哪怕之后不用这个工具，你也能从它这里学到一套"如何组织前后端共享类型"的思路，这个思路本身就能帮你减少很多低级 bug。