1. 项目概述T4 Stack一个面向未来的全栈开发新范式如果你和我一样在过去几年里一直在全栈开发领域折腾从传统的MERN、MEAN到后来火热的T3 Stack再到各种Serverless框架你可能会感到一丝疲惫。每次启动新项目都像在玩一场“技术选型俄罗斯轮盘赌”——选对了库项目顺风顺水选错了后期维护就是一场灾难。更别提还要兼顾Web、iOS、Android甚至桌面端光是搭建一个能跑通所有平台的开发环境就足以消耗掉一个下午的热情。就在我几乎要接受这种“分裂”是开发生态常态时我遇到了T4 Stack。它不是一个全新的框架而是一个经过精心挑选和整合的全栈、类型安全、跨平台应用开发套件。它的核心目标极其明确用一套代码构建能在Web、iOS、Android、macOS、Windows和Linux上运行的应用并且部署在Cloudflare的边缘网络上实现极致的开发体验和性能。我第一次用bun create t4-app命令创建项目时6秒完成依赖安装30秒后端部署上线的速度让我这个老开发有点恍惚。这背后是Bun运行时、Hono.js、Cloudflare Workers等一系列现代工具链的强力组合。T4 Stack的“T”代表Tamagui、tRPC、TypeScript和Tauri但它远不止是四个字母的堆砌而是一套完整的、开箱即用的生产力解决方案。它帮你做出了那些艰难但正确的技术决策让你能跳过配置地狱直接开始构建产品功能。2. T4 Stack核心架构与设计哲学拆解2.1 为何是“全栈”与“跨平台”的终极缝合怪传统的跨平台方案如React Native for Web往往在样式一致性、导航逻辑、数据流上存在大量妥协和平台特定代码。T4 Stack的野心在于它试图从根本上统一开发模型。它的设计哲学建立在几个关键洞察之上UI层的真正统一仅仅共享业务逻辑是不够的UI组件和样式系统也必须能无缝适配不同平台。这就是选择Tamagui作为核心UI Kit的原因。Tamagui不仅提供了一套美观的组件更重要的是它通过编译时优化将你的样式代码在构建时转换为最高效的平台原生代码如React Native的StyleSheet或Web的CSS同时保持了极致的类型安全。这意味着你写的Text color$blue10在Web上是CSS类在Native上是原生样式属性但代码只有一份。类型安全贯穿始终从数据库SchemaDrizzle到API接口定义tRPC再到前端状态和表单验证ValibotT4 Stack强制使用TypeScript并辅以这些类型工具构建了一条从数据库到UI组件的端到端类型安全链路。你修改了后端的一个接口返回值类型前端的TS编译器会立刻报错而不是等到运行时才发现字段不存在。这种开发体验的提升是革命性的。边缘优先的部署策略选择Cloudflare Workers和D1作为后端并非偶然。传统Node.js服务器或容器化部署在冷启动、全球延迟和成本上存在固有瓶颈。Workers作为边缘函数在全球数百个节点运行你的API逻辑用户无论在哪里请求都能抵达最近的节点获得极低的延迟。D1作为边缘SQLite数据库虽然目前有复制延迟的考量但对于多数读多写少的应用场景它能提供强大的本地查询性能。T4 Stack将这套边缘架构作为默认选项是在押注未来应用部署的形态。2.2 技术选型深度解析每一个选择背后的“为什么”运行时Bun vs Node.jsT4 Stack强制要求使用Bun。Bun不仅仅是一个更快的npm替代品。它是一个集JavaScript运行时、包管理器、打包器、测试运行器于一身的工具链。其优势在于极速安装与启动用Zig编写直接调用系统API避免了Node.js的中间层依赖安装速度是npm/yarn/pnpm的数十倍。对TypeScript和JSX的原生支持无需ts-node或tsx直接运行.ts、.tsx文件简化了开发脚本和工具链配置。与Cloudflare Workers的高度兼容性Bun的运行时API设计部分参考了WinterCG标准这使得在本地开发时模拟Workers环境更为顺畅。后端框架Hono.js vs Express/Fastify在边缘函数环境中框架的轻量级和适配性至关重要。Hono.js专为边缘计算设计其特点包括超轻量级极小的包体积符合边缘函数对冷启动速度的严苛要求。优异的TypeScript支持提供极其优雅的类型推断与tRPC集成后能实现完美的API类型推导。中间件兼容性虽然生态不如Express丰富但核心中间件齐全且设计更现代化。状态与数据流Jotai TanStack Query tRPC这是一个“黄金组合”。tRPC定义了类型安全的API契约。你不再需要手动维护Swagger文档或生成客户端SDKtRPC通过TypeScript类型直接生成前后端共享的类型定义。TanStack Query (React Query)负责数据获取、缓存、同步、更新。它接管了所有异步状态的管理提供了useQuery,useMutation等抽象让你从手动管理loading、error状态中解放出来。Jotai负责客户端全局状态如用户偏好、UI主题。它采用原子化状态模型比Redux更简洁比Context性能更好尤其适合管理那些非异步的、需要跨组件共享的状态。 这三者结合形成了清晰的分层tRPC管类型定义和通信TanStack Query管服务器状态Jotai管客户端状态。性能利器Million.js 与 PattyCake这是T4 Stack在性能优化上的“秘密武器”。Million.js一个React的虚拟DOM编译器。它通过编译时分析将你的React组件转换为更高效的、类似SolidJS的细粒度响应式更新指令。对于数据变化频繁的列表、表格等组件能带来显著的渲染性能提升而开发者几乎无感知。PattyCake一个零运行时的模式匹配编译器。它通常与ts-pattern库结合使用用于处理如TanStack Query返回的{ isLoading, error, data }等多种状态。ts-pattern在运行时进行模式匹配而PattyCake可以在构建时将这些匹配逻辑编译掉进一步减少打包体积和运行时开销。3. 从零到一手把手创建并运行你的第一个T4应用3.1 环境准备与项目初始化首先确保你的系统满足以下要求安装Bun这是硬性要求。前往 bun.sh 根据你的操作系统安装最新稳定版v1.0及以上。在终端运行bun --version确认安装成功。准备Cloudflare账户因为默认部署到Cloudflare你需要一个Cloudflare账户。免费套餐足以开始学习和构建中小型项目。安装Wrangler CLI这是Cloudflare的官方命令行工具。通过Bun安装最快bun install -g wrangler。安装后运行wrangler login登录你的Cloudflare账户。注意虽然T4支持Expo用于移动端但在初始Web开发阶段你不需要安装Android Studio或Xcode。移动端开发环境可以稍后按需配置。创建新项目非常简单打开终端在你希望创建项目的目录下执行bun create t4-app my-t4-project这个命令会启动一个交互式CLI询问你几个问题项目名称默认是你指定的my-t4-project。包管理器选择bun推荐。是否初始化Git仓库建议选择Yes。是否使用Tauri实验性桌面支持初次体验建议选No专注于Web和移动端。命令执行后你会看到一个令人振奋的过程依赖安装通常在6秒内完成。进入项目目录cd my-t4-app。3.2 项目结构深度游历让我们看看生成的项目骨架理解T4的代码组织逻辑my-t4-project/ ├── apps/ │ ├── next/ # Next.js前端应用 (Web) │ │ ├── app/ # App Router目录 (Next.js 13) │ │ ├── components/# 共享的React组件 (Web优化) │ │ └── ... │ └── expo/ # Expo前端应用 (iOS/Android) │ ├── app/ # Expo Router目录 (基于文件的路由) │ └── ... ├── packages/ │ ├── api/ # tRPC路由器定义 Hono后端逻辑 │ │ └── routers/ # 你的业务API路由模块 │ ├── auth/ # Supabase认证配置与逻辑 │ ├── db/ # Drizzle ORM Schema 数据库客户端 │ │ └── schema/ # 数据库表结构定义 │ ├── shared/ # **核心**前后端共享的代码 │ │ ├── types/ # 共享的TypeScript类型定义 │ │ └── utils/ # 共享的工具函数 │ └── ui/ # **核心**基于Tamagui的跨平台UI组件 │ └── src/ # 你的按钮、文本、卡片等基础组件 ├── worker/ # Cloudflare Worker入口 (Hono应用) │ └── index.ts ├── drizzle.config.ts # Drizzle数据库迁移配置 ├── wrangler.toml # Cloudflare Worker部署配置 └── package.json # 项目根依赖与脚本关键理解packages/shared和packages/ui是跨平台代码的基石。在这里编写的类型和组件会在apps/next和apps/expo中被同时引用。packages/api定义了你的tRPC路由这些类型会自动同步到前端。worker/index.ts是应用的“后端”入口它导出了一个Hono应用并集成了tRPC适配器。3.3 开发环境启动与热重载T4项目使用Turborepo进行多包管理。在项目根目录下运行以下命令启动完整的开发环境bun run dev这个命令会同时启动Next.js开发服务器通常在http://localhost:3000。负责Web端。Expo开发服务器如果你有移动端环境可以通过Expo Go App扫描二维码预览。本地Cloudflare Workers模拟环境通过wrangler dev启动模拟边缘函数环境API请求会发往这里。打开浏览器访问http://localhost:3000你应该能看到一个默认的T4应用页面。尝试修改apps/next/app/page.tsx或packages/ui/src/MyComponent.tsx中的文字保存后观察页面你会体验到Web和Native如果Expo服务器也在运行同时热重载的流畅感。3.4 构建你的第一个特性一个待办事项列表让我们通过一个简单的“待办事项”功能串联起T4的全栈开发流程。第一步定义数据库Schema在packages/db/schema目录下新建一个todos.ts文件// packages/db/schema/todos.ts import { sqliteTable, text, integer } from drizzle-orm/sqlite-core; import { createId } from paralleldrive/cuid2; export const todos sqliteTable(todos, { id: text(id).primaryKey().$defaultFn(() createId()), title: text(title).notNull(), completed: integer(completed, { mode: boolean }).notNull().default(false), createdAt: integer(created_at, { mode: timestamp }).notNull().$defaultFn(() new Date()), userId: text(user_id).notNull(), // 关联用户为后续认证做准备 });这里使用Drizzle ORM定义了一个简单的todos表。注意字段类型text,integer和约束notNull(),default()。第二步生成并运行数据库迁移在项目根目录运行bun run db:generate。这会在packages/db目录下根据你的schema生成迁移SQL文件。然后运行bun run db:migrate。这个命令会在本地.wrangler目录下创建一个SQLite数据库文件用于开发。执行生成的迁移文件创建todos表。在配置了远程D1后也可以同步到Cloudflare D1数据库。第三步创建tRPC路由在packages/api/routers目录下新建或修改todo.ts// packages/api/routers/todo.ts import { z } from zod; // T4默认使用Valibot但示例先用zod原理相通 import { eq, desc } from drizzle-orm; import { db } from packages/db; // 共享的数据库客户端 import { todos } from packages/db/schema; import { createTRPCRouter, protectedProcedure, publicProcedure } from ../trpc; // 输入验证Schema const createTodoSchema z.object({ title: z.string().min(1) }); const toggleTodoSchema z.object({ id: z.string(), completed: z.boolean() }); export const todoRouter createTRPCRouter({ // 查询所有待办事项 getAll: publicProcedure.query(async ({ ctx }) { // 暂时先不关联用户查询所有 const allTodos await db.select().from(todos).orderBy(desc(todos.createdAt)); return allTodos; }), // 创建新的待办事项后续可改为protectedProcedure create: publicProcedure .input(createTodoSchema) .mutation(async ({ ctx, input }) { const [newTodo] await db.insert(todos).values({ title: input.title, userId: temp-user-id, // 临时用户ID后续接入认证 }).returning(); return newTodo; }), // 切换完成状态 toggle: publicProcedure .input(toggleTodoSchema) .mutation(async ({ ctx, input }) { const [updatedTodo] await db.update(todos) .set({ completed: input.completed }) .where(eq(todos.id, input.id)) .returning(); return updatedTodo; }), });然后在packages/api/root.ts中引入这个路由import { todoRouter } from ./routers/todo; export const appRouter createTRPCRouter({ todo: todoRouter, // ... 其他路由 });第四步在前端调用API并渲染在apps/next/app/page.tsx或任何组件中你可以使用自动生成的tRPC客户端// apps/next/app/page.tsx use client; // Next.js App Router中需要在客户端组件中使用hooks import { api } from ~/utils/api; // 这是项目内生成的tRPC React Query客户端 import { useState } from react; export default function HomePage() { // 使用tRPC钩子获取数据完全的类型安全 const { data: todos, isLoading, refetch } api.todo.getAll.useQuery(); const createMutation api.todo.create.useMutation({ onSuccess: () refetch(), // 创建成功后重新获取列表 }); const toggleMutation api.todo.toggle.useMutation({ onSuccess: () refetch(), }); const [newTitle, setNewTitle] useState(); const handleCreate () { if (!newTitle.trim()) return; createMutation.mutate({ title: newTitle }); setNewTitle(); }; if (isLoading) return divLoading.../div; return ( div h1My Todos/h1 div input typetext value{newTitle} onChange{(e) setNewTitle(e.target.value)} placeholderWhat needs to be done? / button onClick{handleCreate} disabled{createMutation.isLoading} Add /button /div ul {todos?.map((todo) ( li key{todo.id} input typecheckbox checked{todo.completed} onChange{(e) toggleMutation.mutate({ id: todo.id, completed: e.target.checked })} / span style{{ textDecoration: todo.completed ? line-through : none }} {todo.title} /span /li ))} /ul /div ); }至此一个完整的全栈CRUD功能就实现了。你无需手动定义API路径无需编写HTTP客户端TypeScript会确保你调用的方法api.todo.getAll和传递的参数与后端定义完全一致。4. 核心配置详解与生产部署指南4.1 认证集成接入SupabaseT4 Stack默认集成了Supabase Auth。配置步骤如下前往 supabase.com 创建一个新项目。在项目设置中找到Project URL和anon/public key。在T4项目根目录复制.env.example文件为.env。将你的Supabase项目URL和密钥填入.env文件NEXT_PUBLIC_SUPABASE_URLyour-project-url NEXT_PUBLIC_SUPABASE_ANON_KEYyour-anon-key SUPABASE_SERVICE_ROLE_KEYyour-service-role-key (用于服务端操作谨慎保管)重启开发服务器。现在packages/auth模块中的工具函数就可以正常工作了。你可以使用createServerClient在API路由中验证用户或使用createBrowserClient在前端实现登录/注册。4.2 样式系统深入Tamagui配置Tamagui的强大之处在于其编译时优化。查看packages/ui/tamagui.config.ts文件这里定义了你的设计系统主题颜色、间距、字体、组件变体等。// 示例扩展默认主题 import { createTamagui } from tamagui; import { config } from tamagui/config/v2; const appConfig createTamagui({ ...config, themes: { light: { ...config.themes.light, // 添加自定义品牌色 brandPrimary: #007AFF, }, dark: { ...config.themes.dark, brandPrimary: #0A84FF, }, }, tokens: { ...config.tokens, // 自定义间距单位 space: { ...config.tokens.space, lg: 20, xl: 32 }, }, }); export type AppConfig typeof appConfig; declare module tamagui { interface TamaguiCustomConfig extends AppConfig {} } export default appConfig;在组件中你可以这样使用import { YStack, Text, Button } from packages/ui; // 这是从你的UI包导入的、经过配置的组件 const MyComponent () ( YStack padding$lg backgroundColor$brandPrimary Text colorwhiteHello Tamagui/Text Button themeactivePress me/Button /YStack );Tamagui会在构建时将$lg、$brandPrimary等token解析为具体的像素值或CSS变量并生成最优化的样式代码。4.3 部署到Cloudflare Pages将你的应用部署到生产环境体验真正的边缘速度。连接你的Git仓库将项目代码推送到GitHub或GitLab。在Cloudflare Dashboard中创建Pages项目进入Cloudflare Dashboard选择“Workers Pages”。点击“Create application” - “Pages” - “Connect to Git”。选择你的仓库。配置构建设置Build command:bun run buildBuild output directory:apps/next/.next(对于Next.js前端)Root directory: (留空如果是Monorepo根目录)配置环境变量在Pages项目的设置中添加你在.env文件中定义的所有变量特别是Supabase和数据库连接信息。部署保存设置后Cloudflare Pages会自动开始构建和部署。首次构建可能稍慢约90秒后续更新会快很多。对于后端APIHono Worker部署更简单。在项目根目录运行bun run deploy这个脚本会使用wrangler将worker/index.ts部署为Cloudflare Worker。你的API端点将拥有一个类似https://api.your-project.workers.dev的地址。前端Next.js应用通过环境变量配置这个API地址。4.4 数据库连接与使用Cloudflare D1开发时使用本地SQLite生产环境则需要连接到Cloudflare D1。创建D1数据库wrangler d1 create my-t4-database这个命令会在Cloudflare上创建一个D1数据库并在你的wrangler.toml文件中添加配置。运行远程迁移wrangler d1 execute my-t4-database --file./packages/db/migrations/0001_initial.sql或者T4项目通常配置了bun run db:migrate:remote脚本一键执行。更新环境变量在Cloudflare Pages和Worker的环境变量中设置数据库连接信息通常通过wrangler.toml绑定无需手动设置变量。现在你的生产环境应用就连接到了一个全球分布的边缘SQLite数据库。5. 实战避坑与高级技巧5.1 常见问题与解决方案速查表问题现象可能原因解决方案bun create t4-app失败或极慢网络问题或Bun版本过旧1. 检查网络尤其是访问GitHub和npm。2. 运行bun upgrade确保使用最新版Bun。开发服务器启动后页面无法访问或API 404端口冲突或Wrangler开发服务器未正常启动1. 检查终端输出确认Next.js3000端口和Wrangler8787端口是否都成功启动。2. 尝试bun run dev --port 3001指定其他端口。tRPC调用类型错误或智能提示不工作TypeScript服务未正确识别Monorepo路径别名1. 在VSCode中打开项目根目录而不是apps/next。2. 运行bun run type-check检查全局类型错误。3. 重启TypeScript语言服务器在VSCode中执行CtrlShiftP- “TypeScript: Restart TS server”。Tamagui样式在Web上生效在Native上不生效Native端Metro打包器未正确配置Tamagui1. 确保apps/expo/app/_layout.tsx中正确导入了packages/ui提供的TamaguiProvider。2. 清理Expo缓存bun expo start --clear。部署到Cloudflare Pages后API请求跨域错误CORSWorker未正确配置CORS头在worker/index.ts的Hono app中添加CORS中间件。T4模板通常已集成检查是否被误删。D1数据库查询在生产环境慢或超时查询未使用索引或数据量过大1. 使用EXPLAIN QUERY PLAN分析查询。2. 为常用查询字段如userId,createdAt添加索引。3. 考虑对大数据集进行分页查询。5.2 性能优化实战心得善用TanStack Query的缓存与预取// 在列表页预取详情页数据 const utils api.useUtils(); const onHoverListItem (id: string) { utils.todo.getById.prefetch({ id }); }; // 使用 staleTime 和 gcTime 精细控制缓存 const { data } api.todo.getAll.useQuery(undefined, { staleTime: 5 * 60 * 1000, // 5分钟内数据视为新鲜不重新请求 gcTime: 10 * 60 * 1000, // 缓存保留10分钟 });Million.js的适用场景它并非万能。对于高度交互、状态频繁变化的组件如大型数据表格、实时图表、拖拽列表Million.js的优化效果显著。但对于静态或简单组件收益不大。可以通过// million ignore注释来排除特定组件避免不必要的编译开销。图像与静态资源优化Next.js提供了优秀的Image组件。在T4中对于跨平台可以使用Tamagui的Image组件它内部会适配平台。将图片等静态资源上传至Cloudflare R2对象存储并通过Cloudflare Images或自定义Worker实现图片优化、裁剪和全球快速分发能极大提升加载速度。按需导入与代码分割T4基于Next.js和Expo本身就支持代码分割。但要注意在packages/ui中定义的大型组件库确保使用的是Tamagui的tamagui/core和tamagui的优化导入它们会在构建时自动tree-shake。5.3 从开发到上线的完整 checklist[ ]本地开发bun run dev成功Web和API功能正常。[ ]类型检查运行bun run type-check无错误。[ ]代码格式化运行bun run format统一代码风格使用Biome。[ ]环境变量核对.env与生产环境Cloudflare Dashboard设置确保一致。[ ]数据库迁移运行bun run db:migrate:remote确保生产数据库结构最新。[ ]构建测试在本地运行bun run build确保无构建错误。[ ]Worker部署运行bun run deploy更新后端API。[ ]Pages部署推送代码到Git主分支触发自动部署或手动在Cloudflare Dashboard触发部署。[ ]功能验证在生产环境URL进行完整的端到端功能测试。[ ]错误监控接入Sentry或类似服务监控运行时错误。5.4 扩展思路当项目规模增长时状态管理升级当Jotai原子数量过多时可以考虑按业务域进行分组或使用jotai/utils中的atomWithStorage来持久化部分状态。API版本化随着产品迭代tRPC API可能需要版本化。可以考虑通过路由前缀如/api/v1/...或输入输出Schema的渐进式演进来处理。测试策略在packages目录下为共享逻辑如工具函数、API路由添加单元测试使用Vitest或Jest。对于UI组件使用React Testing Library。对于E2E测试可以考虑PlaywrightWeb和DetoxMobile。CI/CD优化利用Turborepo的远程缓存将构建缓存存储在Cloudflare R2或类似服务中可以大幅加速CI流水线的构建速度。经过几个月的实际项目锤炼T4 Stack给我的最大感受是“安心”。它提供了一套经过实战检验的最佳实践组合让我能专注于业务创新而不是没完没了地折腾基础设施。从6秒安装到30秒部署这种流畅感一旦习惯就再也回不去了。当然它也不是银弹对Cloudflare生态的深度绑定是一把双刃剑但就目前来看对于追求极致开发体验和全球性能的应用T4 Stack无疑是一个极具吸引力的起点。如果你正在寻找一个现代、全栈、类型安全的跨平台解决方案不妨用bun create t4-app命令亲自感受一下或许它会成为你下一个项目的默认选择。