1. 项目缘起为什么我会想做一个叫 t3code 的东西t3code 这个名字第一次看到的人可能会觉得有点奇怪。t3 是什么code 又代表着什么其实这里面的逻辑很简单我在实际开发中反复遇到一个痛点每一次启动新项目都要花大量时间在环境配置、目录结构搭建、基础组件封装、请求层设计这些事情上。不同项目的初始化方式还不一样有的用这个脚手架有的用那个模板时间长了之后维护成本越来越高团队里每个人的项目结构也五花八门。所以我决定做一件事把过去几年里踩过的坑、沉淀下来的最佳实践全部固化到一个统一的工程模板里。这个模板我给它取名叫 t3code寓意是“三端贯通、一套代码打天下”。所谓三端指的是 Web 端、移动端和桌面端所谓 code就是把这套能力抽象成一整套可直接复用的代码基础设施。t3code 本质上是一套基于前后端同构思想的全栈项目模板同时自带了代码生成器和在线编辑器能力目标是让开发者能从零开始在十几分钟内拉起一个具备完整工程能力的前端应用。这个项目适合谁来用简单来说适合那些不满足于“只会用脚手架”的开发者尤其是需要对项目结构有完全掌控力的团队。也适合独立开发者一个人要维护多个项目如果不把基础设施统一起来迟早会被重复劳动拖垮。如果你正在做中后台系统、小程序 H5、桌面端工具类应用t3code 这套方案可以直接帮你省掉前期最痛苦的搭架子阶段。2. 整体设计思路与技术选型2.1 前后端同构一个模型三端复用t3code 的核心思路是前后端同构。大部分传统项目的做法是前端一套代码后端一套代码两边的数据模型、校验逻辑、接口定义各写各的一旦业务规则发生变化经常出现两边不同步的情况。比如后端改了某个字段的校验规则前端忘了改线上就会报出一堆奇怪的错误。t3code 的做法是把这些共享的部分单独抽取出来形成一个“共享核心层”前端和后端都从这一层派生自己的代码。实际的目录结构是这样的t3code/ ├── apps/ │ ├── web/ # Web 端应用 │ ├── mobile/ # 移动端应用 │ └── desktop/ # 桌面端应用 ├── packages/ │ ├── core/ # 核心数据模型、工具函数、常量定义 │ ├── ui/ # 跨端 UI 组件库 │ ├── api/ # 接口请求层统一的 HTTP 客户端封装 │ └── cli/ # t3code 命令行工具 ├── templates/ # 项目模板目录 ├── generator/ # 代码生成器 └── docs/ # 文档packages/core 是整棵树的根。所有数据模型、枚举、校验函数都放在这里Web、移动端、桌面端共享这一份代码。这样做的好处是什么假设业务里有一个订单状态枚举传统的写法是前端一份、后端一份、数据库注释里再写一份。在 t3code 里只需要定义一次三个端全部从这里引用。后续要加一个状态改一处三端生效不会出现“前端已经加了后端还在报错”这种尴尬局面。2.2 技术栈选型的底层逻辑t3code 的技术选型没有追逐最新、最热的东西而是选了一套符合“长期维护”需求的组合。Web 端采用 Vue 3 TypeScript Vite移动端采用 Taro 来编译到微信小程序和 H5桌面端采用 Electron 封装逻辑。后端虽然是模拟数据为主但预留了 Node.js 中间层的接口结构方便后续接入真实后端。为什么选 Vue 3 而不是 React没有绝对的对错。我的理由是这样的Vue 3 的组合式 API 在代码组织上更接近于“按功能划分”而不是“按生命周期划分”对中小团队来说更容易上手。Taro 在跨端编译这件事上做得比较成熟一套代码可以同时出微信小程序和 H5显著降低移动端的维护成本。Electron 则是当前桌面端唯一比较靠谱的选择虽然体积是个老大难问题但它的生态最完善遇到问题查资料也容易。还有一个关键决定全链路使用 TypeScript。这里我需要多说一句TypeScript 不是在给你增加工作量而是在给你的项目上保险。在 t3code 的设计里所有 API 请求的入参和出参都有完整类型定义前端调用接口的时候参数错了编译期直接报错。这比运行时炸出一个红色错误提示要舒服得多。2.3 单仓库管理模式t3code 采用了 monorepo 的单仓库管理方式。刚开始做这个项目的时候我自己也纠结过要不要把 Web、移动端、桌面端拆成三个独立的仓库。后来实践下来发现拆开之后问题更多跨端共享的代码没办法直接引用只能发 npm 包而发包的版本管理又是一堆破事。最终决定用 pnpm 的 workspace 功能把三端放在一个仓库底下管理。pnpm workspace 的优势主要有三点依赖安装速度快硬链接机制让同一份包不会被重复下载严格的项目隔离每个子包都有自己的依赖声明不会出现“这个应用能跑是因为另一个应用装了某个依赖”这种隐患本地开发的包之间可以直接引用core 包改了代码三端立即生效不需要发版这套方案在公司内部实践了大半年稳定性一直很好。3. 核心功能拆解t3code 到底能做什么3.1 代码生成器的完整流程t3code 自带一个代码生成器模块解决重复造轮子的问题。它的核心能力是你只需要定义一个数据模型它就能帮你生成一整套增删改查的页面代码。注意这里不是那种简单的“生成一个表单”而是从数据模型定义开始生成完整的表格页、表单页、接口调用层、类型定义、前端状态管理等全套代码。生成器的工作流程分四步解析用户编写的 schema 文件JSON 格式根据 schema 生成 TypeScript 类型定义和数据校验函数生成基于 prisma schema 的后端 mock 数据服务生成前端列表页、表单页的 Vue 组件代码并自动注册路由举一个例子假设要做一个用户管理页面只需要在 schema 文件里这样定义{ modelName: User, fields: [ { name: id, type: string, primary: true }, { name: name, type: string, required: true }, { name: email, type: string, required: true }, { name: status, type: enum, enum: [active, disabled] } ] }执行t3code gen user之后生成器会产出以下文件src/ ├── api/ │ └── user.ts ├── components/ │ └── user/ │ ├── UserList.vue │ └── UserForm.vue ├── types/ │ └── user.ts └── router/ └── user.ts生成的列表页默认支持搜索、筛选、分页表单页默认带校验逻辑。在这个基础上你只需要根据自己的业务场景做一些微调不需要从零开始写。我实测过一个简单的单表管理页面从定义 schema 到页面能跑起来大概三分钟就够了。3.2 请求层封装的细节设计请求层是所有前端项目最容易出问题的地方。t3code 里对这个模块做了非常细致的封装解决的核心问题是统一鉴权、统一错误处理、统一响应格式。请求层的设计思路是封装一个http方法内部处理 token 的注入、错误码的拦截、超时重试等逻辑。上层接口模块只需要明确自己的参数和返回类型不需要关心这些细节。// packages/api/src/http.ts import axios from axios const http axios.create({ baseURL: import.meta.env.VITE_API_BASE ?? /api, timeout: 15000 }) http.interceptors.request.use((config) { const token getToken() if (token) { config.headers.Authorization Bearer ${token} } return config }) http.interceptors.response.use( (response) { const res response.data if (res.code ! 0) { // 统一业务错误处理 notifyError(res.message) return Promise.reject(new Error(res.message)) } return res.data }, (error) { if (error.response?.status 401) { // 登出并跳转登录页 clearToken() redirectToLogin() } notifyError(网络请求异常请稍后重试) return Promise.reject(error) } )有一个细节值得单独拿出来说接口出参的类型安全。t3code 强制要求每个接口函数都要有明确的入参出参类型不允许出现 any。这个约束在刚开始的时候会增加一些工作量但维护了半年之后你会发现你改一个接口的返回结构所有用到这个接口的地方编译期就会把所有需要调整的地方全部暴露出来。这种安全感是运行时测试给不了的。3.3 路由与权限控制的联动机制权限控制是后台管理系统里绕不开的坑。t3code 采用了一种比较实用的方案前端权限基于路由守卫判断后端权限基于 mock 数据模拟两者之间的角色信息通过统一状态管理同步。具体实现上路由配置里每个路由可以声明meta.roles字段表示哪些角色可以访问。路由守卫在跳转前检查用户角色是否在允许列表中router.beforeEach((to, _from, next) { const userStore useUserStore() if (!userStore.isLoggedIn) { if (to.path /login) { next() } else { next(/login?redirect${encodeURIComponent(to.fullPath)}) } return } const roles to.meta.roles as string[] | undefined if (roles !roles.some((r) userStore.roles.includes(r))) { next(/403) return } next() })这套方案的优点是直观、好理解适合绝大多数中后台项目。如果你的项目权限粒度非常细需要控制到按钮级建议在此基础上再加一个自定义指令做细粒度校验但基础的页面级权限控制用这套方案已经足够稳定了。4. 从零到一使用 t3code 搭建一个完整项目4.1 环境准备与初始化要上手 t3code你本机需要有 Node.js 18 以上版本和 pnpm 包管理器。安装命令用的是 pnpm你直接执行pnpm add -g t3code全局安装完成后可以用t3code --help查看所有可用指令。初始化的核心命令是 createt3code create my-project这个命令会询问你几个基础问题包括项目名称、需要启用哪些端web/mobile/desktop、UI 风格偏好等。回答完之后CLI 会基于 templates 目录下的预设模板复制一份完整的工程代码到你的目标目录里然后自动执行依赖安装把基础环境跑起来。这一步最贴心的是初始化完成之后不会让你对着一个空壳子发愁而是直接生成一个带示例页面的可用项目。你打开浏览器能看到的不是一个 hello world而是一套完整的布局框架包含侧边栏、顶栏、用户信息下拉菜单和三个示例页面首页、列表页、表单页。这样你可以先去了解整个项目的代码组织方式再动手改。4.2 核心构建流程演示项目初始化之后下一步通常是把示例代码改成自己的真实业务。我拿列表页改造这个场景来演示完整流程。假设你要做一个“项目管理”页面。第一步定义数据模型。打开schema/project.json写清楚字段定义{ modelName: Project, fields: [ { name: id, type: string, primary: true }, { name: name, type: string, required: true }, { name: owner, type: string, required: true }, { name: status, type: enum, enum: [planning, running, done] }, { name: deadline, type: date } ] }然后在项目根目录执行t3code gen project生成器会产出新的接口层、组件和路由业务代码自动挂载到应用里。打开侧边栏菜单里已经多了“项目管理”这个入口。点进去左侧是筛选条件区右侧是数据表格支持搜索和分页。你可能需要根据自己的业务流程改一些逻辑但骨架已经全部齐了。接下来是登录对接。t3code 自带的登录页面默认连的是 mock 服务登录接口的逻辑在apps/web/src/api/auth.ts里。切换到真实后端的时候只需要改这个文件里的请求路径并确认响应格式和封装层保持一致就可以。4.3 构建、测试与部署建议项目开发完成后t3code 提供了统一的构建命令。因为是 monorepo 结构构建的时候需要注意依赖的构建顺序。如果直接用 pnpm 递归构建core 包还没编译完就去构建 web会找不到产物。t3code 的 CLI 内置了拓扑排序逻辑会自动先构建依赖再做应用构建t3code build web构建产物会输出到apps/web/dist目录你把它丢到任意静态服务器或者 Nginx、对象存储的静态网站托管服务上都能跑。部署的关键点在于接口请求地址。t3code 通过环境变量来区分不同环境# .env.production VITE_API_BASE/api如果你是把前端部署在某个域名的子路径下还要注意配置base路径避免静态资源 404。这些都是小问题但真到了上线那天每一个都能让你折腾半小时起步。所以建议在项目开发第一天就把这些环境配置梳理清楚后续能省不少事。5. 常见问题与排查技巧实录5.1 依赖安装失败的排查思路用 t3code 初始化项目最常遇到的问题就是依赖安装失败。这类问题绝大多数出在网络环境和 pnpm 的版本上。我自己的排查顺序是先看 pnpm 版本是否符合要求。t3code 要求 pnpm 8 以上版本太老会导致 workspace 协议解析失败。查看 registry 配置。如果你之前设置过镜像源偶尔会出现镜像站同步不及时的情况。可以临时切换回来试一下。删除 node_modules 和 pnpm-lock.yaml重新安装。这能解决相当一部分玄学问题。pnpm clear rm -rf node_modules pnpm-lock.yaml pnpm install有一个细节值得注意如果你修改了某个子包的依赖记得在这个子包目录下单独执行pnpm install而不是直接在仓库根目录执行。直接在根目录装会导致子包的依赖声明被 workspace 的根依赖覆盖出现非常难排查的版本冲突。5.2 跨端运行表现不一致的问题t3code 的核心卖点是一套代码跑三端但跨端的坑是客观存在的尤其是移动端编译到小程序的时候。最常见的坑是 Web 端的 DOM API 在小程序里不存在。比如window.localStorage在 Web 端可以正常用在小程序里会直接报错。t3code 在 core 包里封装了一个跨端存储模块统一处理三端的存储差异// packages/core/src/utils/storage.ts export const appStorage { get(key: string): string | null { if (process.env.TARO_ENV weapp) { return Taro.getStorageSync(key) } return localStorage.getItem(key) }, set(key: string, value: string): void { if (process.env.TARO_ENV weapp) { Taro.setStorageSync(key, value) } else { localStorage.setItem(key, value) } } }这类问题只要做到了统一封装层基本都能解决。怕就怕在代码里到处直接调用平台 API一旦散乱了排查起来就非常痛苦。所以我的经验是所有跨端 API 的使用必须收敛到一个公共模块里禁止在业务代码里直接调平台能力。5.3 模块热更新失效的快速恢复方案开发模式下偶尔会遇到 Vite 的热更新失灵。现象是改了代码之后页面没有自动刷新比如新增路由后左侧菜单没有同步变化。大多数情况下是因为新增文件时模块依赖图发生了变化Vite 需要重启才能重新识别。遇到这种情况你不需要手动重启开发服务。t3code 脚手架里内置了一个脚本会自动清理缓存并重启 Vite 进程t3code dev --fix-hmr建议把热更新失灵当成正常现象来对待遇到之后不用焦虑。前两次可能还会觉得项目出问题了后面就很自然地跑一下修复命令继续写代码。5.4 常用命令速查表命令作用使用场景t3code create name创建新项目初始化项目t3code gen model根据 schema 生成代码新增一个业务模块t3code dev启动开发服务日常开发t3code build构建生产环境产物提测或发布t3code lint执行代码检查提交代码前的自检t3code dev --fix-hmr修复热更新失灵问题开发中遇到 HMR 不生效6. 在线编辑器扩展让 t3code 脱离本地环境t3code 还有一个额外的功能模块在线代码编辑器。这个模块不是核心卖点但作为补充能力它解决了一个实际使用场景里的问题——当你在演示项目、临时改代码或者手边没有本地开发环境的时候可以快速打开一个云端版本的 t3code 工程。在线编辑器的基础技术栈组合是 Monaco Editor 加 WebContainer 模拟 Node.js 环境。核心交互逻辑是左侧文件树中间代码编辑区右侧实时预览窗口。这里的实现关键是文件系统协议的统一封装不是在文本编辑器里简单拼接字符串而是通过虚拟文件系统操作真实的项目目录结构。实测下来的体感是代码提示比本地 IDE 会慢一些尤其在项目大了之后内存占用会显著上升。所以在线编辑器适合做轻量级使用场景演示、修改配置文件、临时调样式。重度开发还是建议老老实实用本地的 t3code 脚手架。7. 一些实操过程中的真实心得体会t3code 做到现在我最满意的地方不在于它的代码质量而在于它改变了我的工作方式。我现在的日常开发流程变成了接到需求先花十分钟想清楚数据模型然后跑一次t3code gen剩下的时间全部花在业务逻辑的打磨上。项目结构的统一也让我维护多个项目的时候轻松了很多因为不管哪个项目打开文件树的瞬间我都知道自己该去哪找什么。最后再分享一个写给新手的建议。如果你是第一次接触 monorepo 架构可能会被多层级的目录结构劝退。这个非常正常我刚开始也很不适应光搞明白 packages 底下那堆依赖声明之间的关系就花了不少时间。但我的经验是先不要死磕架构的每个细节直接跟着 t3code 初始化一个项目把示例代码跑起来然后找一个简单模块用生成器生成一遍改一遍。跑完这两个流程之后你再看这套架构的代码组织会发现自己已经能理解了。工具始终是拿来用的用起来之后一切都比想象中简单。
