干我们这行的，最怕的不是写代码，是“搭架子”。我见过太多人为了做一个简单的全栈demo，先花一晚上去折腾Next.js、TypeScript、Prisma、tRPC、Tailwind的版本兼容，再花一晚上配置eslint和tsconfig。t3code就是从我这些踩坑经历里长出来的一个命令行脚手架工具：它把这些日常Web开发里最常用的技术组合固化成一个可交互的初始化器，跑一条命令、回答几个问题，就能得到一个开箱即用的TypeScript全栈项目骨架。

在聊具体用法之前，先把这个工具解决的核心问题说清楚：项目初始化阶段大量重复劳动、模板复制后各种隐患、团队工程规范没法统一落地。它适合两类人，一类是想要快速验证想法、不希望被配置细节淹没的独立开发者；另一类是团队前端负责人，需要给多个项目建立统一入口、减少代码结构漂移。下面我把整个工具的设计思路、实操流程和踩坑记录展开讲。

1. 为什么还需要一个脚手架工具

1.1 每次开局都在重复劳动

先说说项目初始化的真实成本。如果你直接用 create-next-app，默认生成的只是一个“能跑”的 React 应用，TypeScript 配置很基础，样式体系、数据库、接口层完全空白。接下来你要手动加 Prisma、加 tRPC、加 Tailwind，每加一个都要处理版本兼容、约定目录结构、调整 eslint 规则，还要保证几个库之间的类型能相互感知。这个过程最折磨人的不是某个具体步骤有多难，而是没有任何创造性，但它会连续打断你的心流。

我自己做过一次统计：从零搭一套“Next.js + TypeScript + Prisma + tRPC + Tailwind”的可维护骨架，在不踩任何坑的前提下，平均也要40到60分钟。如果中途遇到 Prisma 版本升级导致 API 变化、Next.js 某个配置项在新版本里废弃了，时间直接翻倍。一个人一年初始化个十几次项目，浪费掉的时间足够读完好几本技术书了。

1.2 直接复制模板的隐藏问题

肯定有人会说，我把自己以前的项目复制一份改改不就行了。这个方案短期看很高效，长期看问题很大。试想一下，你的老项目里往往沉淀了大量业务代码、缓存目录、写死的配置、甚至还有一堆临时测试文件。复制过来之后，要么你花半小时清理垃圾，要么带着旧依赖一路升级，最后比从零配置还慢。

还有一个更隐蔽的问题：多人协作时“复制模板”没有统一入口。团队里每个人都在自己某一次项目中复制了一份作为起点，几年之后每个项目的目录结构、代码风格、依赖版本已经分叉得妈都不认识了。新人进来之后问“我们项目的标准结构是什么”，没人能给出一个准确答案，只能拿某个老项目当参考。t3code 把初始化和模板管理做成工具之后，本质上是在项目生命周期的最前端建立了一条规范入口，从源头上减少这种漂移。

1.3 工具定位：不只是初始化

t3code 不是简单的 create-t3-app 替代品。它包含三个层面的设计，这是它和其他脚手架的核心区别：

• 第一层是快速初始化：交互式选择模块，生成干净、可运行的项目骨架。
• 第二层是约定与扩展：内置统一目录结构、lint 规则和最佳实践配置模板，保证每个新项目长得很像。
• 第三层是模块模板体系：支持把认证、后台管理等业务模块作为模板追加到现有项目中，而不是每次从零生成。

如果只把它当“样板代码拉取器”用，格局就小了。它更像团队里的“工程生成器”，你前期花十分钟定制好模板，后续几十个项目都能享受这套规则带来的红利。

2. 环境准备与安装

2.1 安装前的环境检查清单

在安装 t3code 之前，先花两分钟确认环境，避免后面报出莫名其妙的依赖错误。

为什么这么强调 Node 版本？因为 t3code 生成的项目顶层依赖（Next.js、Prisma、tRPC、TypeScript）对 Node 版本有硬性要求。Node 版本过旧时，很多报错会出现在编译链路的最深处，比如某个依赖编译失败、某个 API 找不到，排查起来特别费劲。我见过最典型的一个案例：同事用 Node 16 跑 create 出来的项目，Next.js 构建时报错“Invalid character”，他折腾了一下午，最后发现是 Node 版本问题。所以在安装工具之前，先执行node -v看一眼，输入输出里有个版本信息，后面所有怪问题都能少一半。

2.2 安装与第一条命令

环境检查没问题，直接执行：

# 使用npm全局安装 npm install -g t3code # 查看版本，确认安装成功 t3code --version

安装完成后，运行t3code create，工具会进入交互式问答。需要填写的配置项包括项目名称、技术栈模块（Next.js / TypeScript / Prisma / tRPC / Tailwind，默认全选）、包管理器、是否初始化 Git、是否包含示例代码。创建完成后的项目目录结构大致如下：

my-app/ ├── prisma/ │ ├── schema.prisma │ └── seed.ts ├── src/ │ ├── pages/ │ │ ├── index.tsx │ │ └── ... │ ├── server/ │ │ └── api/ │ ├── styles/ │ │ └── globals.css │ └── utils/ │ ├── api.ts │ └── ... ├── .env ├── .eslintrc.json ├── next.config.mjs ├── tailwind.config.ts ├── tsconfig.json └── package.json

2.3 为什么强烈建议用 pnpm

我在生成项目时一般选 pnpm，原因有两个，都是实战中踩出来的。第一，pnpm 的符号链接机制天然隔离依赖，不会出现“我本地能跑，CI 上装完依赖构建就报错”的幽灵依赖问题。npm 会把所有间接依赖都平铺到 node_modules 顶层，某个包能在开发环境访问到它依赖的依赖，换个环境可能就装不出同样的树，这种不可复现问题非常恼人。第二，pnpm 的硬链接存储机制让安装速度明显更快，尤其是团队里多个项目依赖同一套技术栈时，全局 store 只需要存一份，安装新项目只要创建链接。

如果你的团队被公司策略锁死在 npm，也不是不行，只是要注意同一个项目在 npm 和 pnpm 下可能因为依赖提升规则不同出现细微差异。最好在项目根目录里写好 README，明确注明推荐的包管理器，别让同事自己猜。

3. 初始化项目实操

3.1 创建项目的完整流程

实际跑一次t3code create，交互过程大概是这样的：

1. 输入项目名my-app。
2. 选择要包含的模块，我一般全选：Next.js、TypeScript、Prisma、tRPC、Tailwind。
3. 选择包管理器pnpm。
4. 选择是否需要示例代码，新手建议选“包含”，老手选“最小化”。
5. 是否自动初始化 Git 仓库，建议选是。

这里专门说一下第四步。很多人为了省事直接选“最小化”，结果是项目骨架虽然干净，但连 tRPC 的客户端封装、Prisma 的初始化代码都需要自己重新摸索，反而把一个本来应该很顺滑的过程拖长了。我建议第一次用 t3code 的人选择“包含示例代码”，生成之后先跑起来，再去阅读示例里的代码实现，理解 tRPC 和 Prisma 在项目里的完整链路。等你自己已经熟练掌握了这套模式，后续生成新项目再选“最小化”。

3.2 目录结构到底在说什么

目录结构不是随便摆的，每一个目录都有它的工程化考量。我挑几个关键目录解释一下：

• prisma/schema.prisma：这是数据模型定义文件，Prisma 会根据它生成类型安全的数据库客户端。t3code 默认带 User 和 Post 两个示例模型，方便你直接看到一对一、一对多关系怎么建模。

• src/server：服务端代码目录，tRPC router 和业务逻辑都放这里。为什么单独分出来一个 server 目录？因为 Next.js 的 RSC（React Server Components）模式下，页面组件有可能是服务端执行的，把 API 逻辑独立出来，有助于避免客户端包体积膨胀，也让服务端代码的边界更清晰。

• src/pages：页面路由目录。这里有一个值得说明的决策：t3code 默认使用 Pages Router 而不是 App Router。不是 App Router 不好，而是 Pages Router 对 tRPC、Prisma 的集成文档最成熟，SSR 与 CSR 模式的切换也简单直接。对生产环境来说，可控性往往比追逐最新范式更重要。

• src/utils：通用工具目录，api.ts里封装了 tRPC 客户端调用，auth.ts处理会话逻辑。把这类代码独立出来，核心页面代码会干净很多。

3.3 几个让人困惑的配置文件

新手最容易忽略next.config.mjs、tailwind.config.ts、tsconfig.json这三个文件，实际上 t3code 生成的项目里，它们藏了一组小心思：

tsconfig.json里开启了strict: true，并配置了@/路径别名映射到src/。有些开发者在项目跑通之后，为了图快会把 strict 关掉，这是典型的下下策。严格模式虽然麻烦，但它会在编译期暴露很多潜在的类型问题，是项目后续持续维护的重要防线。路径别名也不是装饰，它让你在写 import 的时候不用写一长串../../../，代码可读性大幅提升。

tailwind.config.ts里的 content 路径已经限定了源码目录，不会误扫 node_modules 里的大块代码导致构建变慢。如果你往项目里新增了.mdx或.html等扩展名文件，需要把扩展名补进 content 配置里，否则这些文件里写的类名会被 Purge 掉。

next.config.mjs里通常会包含类似下面这样的一行：

experimental: { serverComponentsExternalPackages: ['@prisma/client'], }

这行配置对 Serverless 部署至关重要。没有它，部署到 Vercel 或边缘运行时，Prisma 的查询引擎二进制文件可能打不进产物包，上线的时候就会报PrismaClientInitializationError。很多本地开发一切正常、部署就崩溃的例子，根因都在这。

4. 核心模块的工程化实现

4.1 数据库接入与 Prisma

初始化完成后，第一步通常是确认数据库连接。t3code 默认在.env里给了一个 SQLite 的连接串：

DATABASE_URL="file:./dev.db"

把 Prisma 接进来的完整流程很简单：

# 安装依赖后，先创建数据库表 pnpm prisma db push # 生成 Prisma Client pnpm prisma generate

这里我想强调一个选择：为什么示例项目我用db push而不是migrate dev？因为示例项目里的模型是演示用的，不需要维护迁移历史，db push直接同步 schema 到数据库，速度最快，适合原型期快速迭代。但一旦项目进入多人协作阶段，就要切换到prisma migrate dev，它会把每次 schema 变更记录成迁移文件，让每个协作者都能在同一个数据库结构版本上工作。

默认的schema.prisma长这样：

generator client { provider = "prisma-client-js" } datasource db { provider = "sqlite" url = env("DATABASE_URL") } model User { id String @id @default(cuid()) name String? posts Post[] createdAt DateTime @default(now()) } model Post { id String @id @default(cuid()) title String content String? author User? @relation(fields: [authorId], references: [id]) authorId String? createdAt DateTime @default(now()) }

生产环境切 PostgreSQL 时，只需要把 datasource 里的provider改成"postgresql"，同时把DATABASE_URL换成对应连接串，其他代码基本不用动。这就是 Prisma 的抽象价值：数据模型写一遍，数据库切换的成本被压到最低。

4.2 tRPC 接口链路

t3code 生成的项目里，tRPC 相关的代码分布在三个位置：

• src/server/api/trpc.ts：初始化 tRPC 实例，定义公共 procedure 和受保护 procedure。
• src/server/api/routers/：各个业务 router 文件，根 router 在这里合并。
• src/utils/api.ts：客户端调用封装，提供类型安全的 hooks。

理解 tRPC 链路最关键的一句话：类型是自动推导的。你在服务端定义一个返回{ name: string; count: number }的 query，客户端调用处直接就能拿到对应的 TypeScript 类型，不需要手写任何接口定义文件，也不需要维护 API 文档。重构 API 时，如果改变了返回结构，编译器会直接标红所有引用位置，这种体验比任何文档都可靠。

示例代码里最常见的调用模式是这样：

const users = api.user.getAll.useQuery(); const createUser = api.user.create.useMutation({ onSuccess: () => { users.refetch(); }, });

这段代码覆盖了 tRPC 的查询、变更、失效重取三个核心场景。在实际业务里，十有八九都会用到相似的模式：数据列表加载、表单提交、成功后刷新列表。建议第一次使用的人把这几个模式理解透，后续写业务会顺手很多。

4.3 页面与样式体系

页面部分我一般会先删掉示例代码，再写自己真正的页面。但删之前，建议仔细阅读一下示例里的页面代码，特别是它演示了 tRPC 的useQuery和useMutation用法，以及 Tailwind 在服务端渲染组件里的应用方式。

t3code 的 Tailwind 配置默认开启了 JIT 模式，样式类名按需生成，产物体积小。你在页面里写<h1 className="text-2xl font-bold">，构建时 Tailwind 会扫描源码提取出text-2xl和font-bold这两个类名，生成对应的 CSS，其他用不到的样式不会出现在产物里。这里有一个容易忽视的点：类名必须完整写在源码里，不能通过字符串拼接动态生成，比如className={text-${size} font-bold}，动态拼接的类名 Tailwind 无法扫描到，样式会莫名其妙消失。

5. 自定义扩展与二次开发

5.1 快速新增一个业务模块

t3code 有一个比较实用的功能：模块追加。假设你已经在一个项目上开发了一段时间，现在需要加一个带认证的模块，不需要从零手写，直接执行：

t3code add module auth

它会自动完成几件事：在prisma/schema.prisma里插入认证相关的数据模型，在 tRPC router 里注册认证路由，生成对应的页面组件和配置代码。这套机制本质上是把“复制粘贴再加修改”的过程自动化。模块模板里的占位符会被替换成你的项目名、包名和路由前缀，避免每次复制完手动改名、手动找引用位置。

如果你所在团队有自己的业务模式，比如管理后台、博客、电商商品模块，都可以照着这个机制定制团队内部模板。这样一来，每个新项目启动时，不需要重新讨论“后台怎么组织、权限怎么做”，统一跑一遍 t3code 相关命令就能得到结构一致的代码。模板把工程规范焊死在代码生成器里，人可能偷懒，模板不会。

5.2 部署前的建议清单

把 t3code 生成的项目部署到线上之前，我建议先过一遍下面这份检查清单，每一条都是我踩过的坑：

• 确认.env里DATABASE_URL指向生产数据库，并执行过prisma migrate deploy。很多人本地连的是 sqlite 文件，部署时忘了改，线上直接报数据库连接失败。
• 确认prisma generate在构建阶段会执行。在package.json的postinstall脚本里加上prisma generate，避免构建时 Prisma Client 不存在。
• 检查 Serverless 部署时 Prisma 引擎能被产物体积收集器追踪到。这一步最隐蔽，本地跑得好好的，部署到边缘环境后报PrismaClientInitializationError，大概率是构建机里prisma generate的时机不对或者产物收集器没有把引擎文件打进去。
• 跑一遍pnpm lint和pnpm build，两个都通过再部署。这一条看起来简单，实际能挡住大量低级问题。

6. 高频问题排查实战

6.1 “PrismaClient is not defined” 一类报错

这类报错在开发和生产环境都可能出现，常见原因很简单：schema.prisma里的模型改了，但没有重新生成 Prisma Client。解法也直接，强制重新生成一次：

# 清掉旧的 client 产物 rm -rf node_modules/.prisma node_modules/@prisma/client # 重新生成 pnpm prisma generate

为了避免这种问题反复出现，建议在package.json里加一个脚本：

{ "scripts": { "db:generate": "prisma generate" } }

每次改完 schema 先跑一遍pnpm db:generate，把生成动作变成肌肉记忆。

6.2 Tailwind 样式不生效

Tailwind 样式突然消失，排查优先级最高的就是tailwind.config.ts里的 content 配置。如果你在项目里新增了src/app或者src/views目录，而 content 只写了./src/**/*.{ts,tsx}，那大概率没问题；但如果文件用的是.mdx或者.html扩展名，必须把扩展名补进去，否则里面的类名会被当作未使用代码清除掉。

还有一个小概率情况：浏览器缓存了旧的 CSS 文件，特别是你用了激进的服务端缓存插件，刷新页面还看到旧样式。直接开无痕窗口看一次，问题基本就定位了。

6.3 端口冲突与热更新变慢

开发时遇到端口被占用是最常见的情形，可以临时换端口启动：

pnpm dev -- -p 3001

热更新变慢的问题稍微复杂。最常见的原因是页面里引了体积过大的全局样式文件，或者大量使用了any类型导致 TypeScript 的类型检查在 HMR 链路里拖后腿。如果发现改动一个小组件也要等两三秒才刷新，先看看是不是src/pages里某个父组件 import 了太多东西，把组件拆细就能显著改善。不要一遇到慢就想着改next.config.mjs配置，先检查自己的代码拆分是否合理，这个方向才是真正的根因。

我自己用了 t3code 大半年，最大的体会是这类工具的真实价值不在第一分钟省了多少事，而在于它把工程规范固化到了模板层。人有惰性，很多团队规范写着写着就没人遵守了，但模板不会。后来我们团队接新项目，我都会先在内部问一句“能不能直接跑一遍 t3code”，能的话，开局就少走半天弯路。如果你也在维护类似的脚手架，记得定期更新内置依赖版本，别让新项目一上来就带着旧依赖，那才是真正的长期隐患。