t3code：一套现代前端工程化模板的设计与实践

如果你说“t3code”这个词，大概第一反应是某个开源项目的代号，或者是某个团队内部的工具名。实际上，这是一个我给新项目起的模板代号，全称拆开来看就清晰了：T3 + code。T3 取的是 TypeScript、Tailwind CSS、Turborepo 这三个现代前端工程里出场率极高的技术，code 则指代码规范、提交规范、自动化检查这一整套约定。

说起来，我见过太多新项目死在“起步基建”上：一开始大家凭习惯各写各的，三周后代码风格乱成一锅粥，review 的时候一半时间在争缩进和引号；CI 没接，提交全靠自觉，测试覆盖率形同虚设。t3code 要解决的就是这个问题，把一套已经跑过多个生产项目的工程底座打包成模板，让新项目从第一天就有规范、有检查、有自动化流程。这篇文章就来拆一拆 t3code 的设计思路、核心配置、实操过程和踩坑记录，适合准备从零搭建前端工程化体系的团队，也适合一个人写项目但想省心的开发者。

1. 为什么是 t3code：一套前端工程起点的设计思路

1.1 技术选型背后的真实需求

很多人在选型的时候是“看排行榜”，哪个热门选哪个，但 t3code 的选型逻辑完全不同——它是从团队协作的真实痛点倒推出来的。

TypeScript 不用多说，静态类型给协作兜底。我统计过自己团队过去两个项目的 bug 分布，大概有四成是“运行时才发现类型不对”导致的低级错误，比如接口字段拼错、函数参数传反。TypeScript 不一定减少代码量，但能把这类能在编译期暴露的问题直接拦在提交之前，省下来的联调和查问题时间非常可观。

Tailwind CSS 的争议比较大，喜欢的人说它快，讨厌的人说它脏。我的理解是，Tailwind 真正的价值不是“不用写 CSS”，而是把样式约束在一个设计变量的体系内。t3code 里默认配好了颜色、间距、圆角、字体大小的 token，团队里任何人写的界面，看起来都是一个设计系统出来的，而不是四个人四种风格。这对中小团队来说，比任何设计规范文档都更容易落地。

Turborepo 是这套方案里最容易被忽略但后劲最大的一块。t3code 从一开始就按 monorepo 的形态组织，哪怕你当前只有单个应用，目录结构也保留着 packages 的扩展位。后面要加管理后台、加组件库、加 Node 服务，不需要重构仓库，直接往 packages 里塞就行。Turbo 的增量构建和远程缓存，让 monorepo 以后的构建速度不至于崩掉。

1.2 code 层面：规范不是限制，是省时间

再来说 code。我见过很多团队把“规范”理解成约束，觉得是在给自己上枷锁，实际上规范是降低协作成本最划算的投资。

没有规范的时候，每次 code review 都在争论“这个该不该加分号”“这里用单引号还是双引号”，这种讨论对产品质量毫无贡献，纯粹浪费时间。t3code 的做法很简单：把风格问题全部交给工具自动解决，把人的精力留在逻辑上。ESLint 只开真正能发现问题的规则，比如未使用变量、隐式 any、危险可选链；Prettier 专门管格式；提交前自动跑一遍。规则是机器定的，不是按某个人的口味定的，谁也不吃亏。

这是 t3code 最重要的一个设计原则：把容易产生分歧、没有标准答案的东西变成默认值，团队才能真正在产品问题上达成一致。

1.3 t3code 的结构：模板不只是脚手架

我们需要先分清两件事，脚手架只是“生成目录”，模板是“带默认行为和约束的起点”。

t3code 做的事情比脚手架多三层：

• 配置层：TypeScript 的 tsconfig、ESLint 的扁平配置、Prettier 规则、Tailwind 主题、Husky 钩子、lint-staged 匹配规则，全部预设完毕
• 流程层：pre-commit 自动跑 lint 和类型检查，CI 里跑测试、构建、检查覆盖率，改动会被 Nut 自动收集
• 约定层：目录怎么分、文件怎么命名、组件怎么写、导入顺序是什么，这些写不尽的约定通过配置和插件固化下来

所以 t3code 不是“跑一下 create 然后删掉 demo”，它是一个持续维护的工程底座。新项目基于 t3code 起步，日常改动只需要在沉淀应用代码，基建的部分不用重复造轮子。

2. 核心细节拆解：t3code 的目录与规则配置

2.1 目录结构：为什么这样分

t3code 默认的目录结构长这样：

apps/ web/ # 主前端应用（Next.js） packages/ ui/ # 共享组件库 config/ # 共享配置：eslint、tsconfig、prettier utils/ # 工具函数 types/ # 全局类型定义 scripts/ # 工程脚本 docs/ # 团队文档

有人会觉得，项目就两三个页面，开 monorepo 是不是过度设计了？我在实际用下来的感受是，对于一个人的项目，确实早期的目录拆分感觉多余；但一旦有了第二个人、第二个应用，仓库膨胀的速度比想象中快得多。UI 组件、工具函数从一开始就放在 packages 里，视觉和逻辑边界天然清晰，几年下来不会出现一个几千行的 utils 文件。

2.2 配置层的实现细节

t3code 里的配置都收敛在packages/config这个包里，各应用通过依赖引用来使用。这个设计的巧妙之处在于，当所有配置集中在一个包，新项目继承 t3code 的成本就极低。

ESLint 用的是新版扁平配置（flat config），而不是传统的.eslintrc。扁平配置的好处是去掉了层级继承的隐式行为，规则从哪来的、加了什么 override，全部一目了然。t3code 的 eslint 配置大概分为几个模块：

import { defineConfig, globalIgnores } from "eslint/config"; import tseslint from "typescript-eslint"; import reactHooks from "eslint-plugin-react-hooks"; import prettier from "eslint-config-prettier"; export default defineConfig([ globalIgnores(["**/dist/**", "**/.next/**", "**/node_modules/**"]), ...tseslint.configs.recommended, { plugins: { "react-hooks": reactHooks, }, rules: { "@typescript-eslint/no-explicit-any": "warn", "@typescript-eslint/no-unused-vars": ["error", { argsIgnorePattern: "^_" }], "react-hooks/rules-of-hooks": "error", "react-hooks/exhaustive-deps": "warn", }, }, prettier, // eslint-config-prettier 必须放在最后，用来关掉格式相关规则 ]);

注意规则里no-explicit-any只给了 warn 而不是 error，这是我特意留的口子。完全禁any会让团队在遇到复杂类型时陷入僵局，而 warn 保留了一个表达自由度，又不至于完全无视。no-unused-vars加了argsIgnorePattern: "^_"，这个很重要，因为很多回调函数的参数本身就没用，但直接报 error 很烦人，用_前缀告诉代码检查器“这个参数我故意不用的”，语义也清晰。

Prettier 配置更简单，t3code 直接定了这几个值：

{ "semi": true, "singleQuote": true, "printWidth": 100, "trailingComma": "all" }

printWidth拉到 100 而不是常见的 80，是我测试了很多项目后觉得更合理的宽度——现在屏幕都宽，80 的折行率太高，读起来反而不连贯。

2.3 类型检查：基础配置与延伸

TypeScript 的共享配置放在packages/config/tsconfig.base.json：

{ "compilerOptions": { "target": "ES2022", "module": "ESNext", "moduleResolution": "bundler", "strict": true, "jsx": "preserve", "isolatedModules": true, "esModuleInterop": true, "skipLibCheck": true, "noUncheckedIndexedAccess": true, "resolveJsonModule": true } }

moduleResolution: "bundler"是 TypeScript 5.x 之后的重要选项，它允许配合打包器使用 ESM 风格的导入，不用再写.js后缀，对 Next.js、Vite 这类工具非常友好。noUncheckedIndexedAccess打开后，访问数组或对象索引时会多一个 undefined 的判断，刚开始会觉得烦，但它真的能逼着你处理边界情况，少很多线上 bug。

Tailwind 的配置里有一个细节值得说：content的扫描路径如果写漏了，样式就不会生效。t3code 里统一写成：

export default { content: [ "./src/**/*.{ts,tsx}", "../../packages/ui/src/**/*.{ts,tsx}", ], };

注意第二行——因为组件库在 packages 里，如果 content 只扫描 apps 里的文件，组件库里的 tailwind class 会被 Purge 掉。这个问题我见过太多次了，团队一边疑惑“为什么组件在 dev 模式正常，build 完样式没了”，一边根本想不到是 Tailwind 的 content 配置问题。

3. 实操过程：从零搭建 t3code 并让团队跑起来

3.1 初始化：从一个空目录到可运行仓库

我这边假设你从空仓库开始，手动操作一遍 t3code 的搭建过程。首先初始化一个 pnpm workspace：

mkdir t3code-demo && cd t3code-demo pnpm init

创建pnpm-workspace.yaml：

packages: - 'apps/*' - 'packages/*'

根目录的package.json要写清楚 workspace 的脚本，t3code 习惯的做法是把所有命令放在根上，开新项目或者新人进来只需要记住 5 个命令：

{ "name": "t3code-demo", "private": true, "scripts": { "dev": "turbo run dev", "build": "turbo run build", "lint": "turbo run lint", "typecheck": "turbo run typecheck", "format": "prettier --write ." } }

接着创建turbo.json：

{ "$schema": "https://turbo.build/schema.json", "tasks": { "build": { "dependsOn": ["^build"], "outputs": [".next/**", "dist/**"] }, "lint": { "outputs": [] }, "typecheck": { "outputs": [] }, "dev": { "cache": false, "persistent": true } } }

dependsOn: ["^build"]的意思是构建前先构建依赖它的包，这个配置在 monorepo 里几乎决定了构建顺序的正确性。outputs里的.next/**和dist/**则是 Turbo 缓存的命中路径，没写对的话缓存会一直失效，构建速度也就提不上去。

再初始化应用。t3code 默认用 Next.js 作为 web 主应用，跑：

cd apps pnpm create next-app web --ts --eslint --tailwind --app --src-dir

然后装共享开发依赖：

pnpm add -w -D typescript prettier eslint turbo husky lint-staged cross-env

-w表示装在 workspace 根目录，这样所有包共享同一份工具版本，不会出现子包各自装一遍、版本还不一致的情况。cross-env是特意加的，在 Windows 上设置环境变量的方式跟 Unix 不同，不用 cross-env 的话，同样的脚本在同事电脑上可能跑不起来。

3.2 接入提交规范与自动化检查

git 钩子是 t3code 的第一个自动化闸门。先执行：

git init pnpm exec husky init

Husky 新版（v9）的初始化方式和旧版不一样，不需要husky install，直接在 init 后生成的pre-commit文件里写入要跑的命令。t3code 的 pre-commit 非常简单：

pnpm lint-staged

然后在根目录package.json里配置 lint-staged：

{ "lint-staged": { "*.{ts,tsx}": ["eslint --fix", "prettier --write"], "*.{json,md,yaml}": ["prettier --write"] } }

我故意没把类型检查放进 pre-commit，因为大项目全量 typecheck 可能要跑几十秒，影响提交体验。类型检查放到 CI 里做强制卡点，本地靠编辑器的 TypeScript 插件实时感知，这样既保证质量又不打断开发流。

Husky 的 pre-push 钩子可以用来在推送前做一次全量 typecheck，适合对质量要求更高的场景。t3code 里默认不开启，留了个注释作为提示。

3.3 CI 流水线的关键配置

t3code 的 CI 用的是 GitHub Actions，核心工作流长这样：

name: CI on: pull_request: push: branches: [main] jobs: quality: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: pnpm/action-setup@v4 with: version: 9 - uses: actions/setup-node@v4 with: node-version: 20 cache: pnpm - run: pnpm install --frozen-lockfile - run: pnpm lint - run: pnpm typecheck - run: pnpm build

这里有两个坑必须说明。第一，pnpm install务必用--frozen-lockfile，否则 CI 和本地安装的依赖版本可能不一致，当天本地正常、CI 挂掉，排查大半天最后发现是 lockfile 被悄悄更新了。第二，cache: pnpm依赖 actions/setup-node 对 pnpm 的支持，如果版本配错，缓存不会生效，每次 CI 都要全量装依赖，慢得让人崩溃。

CI 的策略是“三关全过才允许合入”：lint 检查、类型检查、build 产物验证。这三个动作看起来基础，但实际能拦截掉大部分低级问题。一个几百行的 PR，如果跑完 CI 能一次性通过，human review 的负担就小很多，reviewer 可以把精力集中在逻辑设计上。

3.4 让团队第一天就能上手

模板搭好了，还要解决一个实际问题：怎么让新人快速理解目录和约定。t3code 的 docs 目录里放了三份文档：

• getting-started.md：环境准备 + 常用命令 + 启动流程
• architecture.md：目录结构解释 + 数据流约定 + 命名规则
• contribution.md：提 PR 的流程 + 分支命名 + commit message 规范

Commit message 的规范我没用 commitlint，因为给团队引入一套需要记忆的规则，学习成本远大于收益。t3code 只约定一个前缀习惯：feat、fix、refactor、docs、chore、test，能在 commit message 第一行看出来这次提交是做什么的，就够了。

4. 常见问题与排查技巧实录

4.1 最容易踩的四个坑

我在搭建和推广 t3code 的过程中，遇到过不少团队反馈问题，大部分集中在这四个：

Husky 钩子不生效。新版本 Husky 的钩子脚本存放在.husky/目录，而且必须被 git 追踪。有些同学把.husky加进了.gitignore，结果别人 clone 下来后钩子完全失效。检查方法很简单，看.husky/pre-commit有没有 tracked。如果用的是 Windows，还可能出现钩子没有可执行权限，导致提交时静默跳过。

Tailwind 样式在 build 后丢失。这个前面提过，基本都是content配置没覆盖到组件库。建议打开tailwind.config.ts，确认 paths 包含所有引用 tailwind class 的文件目录。

Turbo 缓存不生效。outputs路径跟实际构建产物不一致时，Turbo 每次都会重新构建。尤其是 Next.js 的.next目录，如果任务写的是build但 export 时用了别的目录名，缓存就永远不会命中。用pnpm exec turbo run build --force可以临时清理缓存验证问题是不是出在这里。

CI 中 pnpm 安装失败。最典型的原因是 lockfile 与pnpm-workspace.yaml不一致，改过 workspace 包结构后没重新生成 lockfile。另一种是网络原因，在国内环境建议给 CI 配置镜像源：

pnpm config set registry https://registry.npmmirror.com

但不是说配了镜像就万事大吉，如果之前用过别的源，pnpm-lock.yaml 里记录的 resolved 地址可能还是旧源，把 lockfile 删掉重装一次最省事。

4.2 问题速查表

4.3 排查思路：从通用到具体

排查这些问题，我总结了一套顺序：先从“环境是否一致”入手，再看“配置是否匹配”，最后看“缓存是否失效”。很多问题在本地复现不了、CI 才出现，基本都是环境不一致。当你觉得“明明代码没问题”的时候，先怀疑依赖树和 Node 版本。

有一回团队的 CI 总在 build 阶段报内存溢出，我查了很久才发现是 Node 20 对默认内存的限制变了。解决方式是给 Next.js 的构建脚本加一个环境变量：

{ "scripts": { "build": "cross-env NODE_OPTIONS=--max_old_space_size=4096 next build" } }

NODE_OPTIONS这个环境变量很多人不知道，它在 Node 版本间行为可能有差异，但项目里设置合理的堆内存上限，能避免本地没问题、CI 崩掉这种玄学故障。

最后再分享一点我个人的体会

t3code 从最初的雏形到现在，我带它跑了两个正式项目和一次重构。最直观的感受是，新成员加入时花在环境配置上的时间从“一下午”缩短到“二十分钟”，代码 review 的讨论重心从“这种写法行不行”转移到了“这样设计对不对”，这个过程让我确定它是值得的。

如果你准备在自己团队落地 t3code，我的建议是不要照搬。每个人、每个团队的开发习惯都有差异，模板的意义是提供一个默认值，而不是终点。把默认值跑起来，再根据自己的情况慢慢调整规则，可能这才是工程模板真正应该有的样子。