企业官网建设流程全解析

t3code是我在前端团队里逐步落地的一套代码质量保障方案，名字里的t3，指的是TypeScript、Testing、Tooling三个关键词的首字母。简单说，它把日常开发里最容易产生争议的几件事——代码格式、语法规则、类型安全、单元测试——全部收敛到自动化工具链里，让约定变成机器检查，而不是人肉评审。这篇内容我会尽量讲得贴近实操，适合正在搭建或重构前端工程化体系的技术负责人、前端工程师，也适合一个人维护多个项目、想统一代码风格的独立开发者。如果你正被"格式化争论、ESLint警告堆积、CI上测试才跑挂"这些事困扰，t3code这套思路可以直接给你参考。

我先解释一下名字。有人会把它和社区里那个T3 Stack（Next.js、tRPC、Tailwind三件套）混淆，我这里说的是自己的工程实践项目，核心是"TypeScript + Testing + Tooling"三者形成的闭环。TypeScript负责类型约束，Testing承接行为验证，Tooling统一格式与规范。这三者一旦在提交前后的链路里真正跑起来，团队里的很多无效沟通会立刻减少，Code Review的焦点也能从"这里该不该加分号"转移到真正的业务逻辑上。

1. t3code到底解决什么问题

1.1 最让人头疼的从来不是技术难点，而是规范分歧

不少团队都有过这种阶段：项目能跑，文档也有，但每次看代码总觉得别扭。打开任何一个文件，你会看到混用的单双引号、4个空格和2个空格交替、没排过版的import语句、随手写的any类型。更麻烦的是，每个成员用自己习惯的编辑器配置，保存文件时有的自动格式化，有的完全不处理。结果就是，一次功能改动几十行，真正的业务逻辑可能只有十几行，剩下全是格式diff。Code Review的时候，评论区和私聊光是在"缩进风格"上来来回回就能聊半天。

我经历过最夸张的一次，是两个人因为"对象属性最后一项该不该写逗号"在review里争论了两个小时。事后复盘，这种争议纯属工具链缺位。人应该把精力花在判断设计方案是否合理、边界条件是否覆盖到位，而不是纠结机器就能统一规则的事。t3code解决的就是这个层面的问题：用pre-commit钩子把格式规则挡在提交之前，代码根本走不到review环节就已经经过了一次机器审查。

还有一个隐蔽的问题是把类型检查放在最后一步。很多项目本地跑得通，为什么CI却挂掉？因为本地开发时，编辑器报的黄线不被重视，控制台的警告太多也被忽略，但CI上执行的是严格模式，一跑就爆。于是出现"我的环境没问题啊"这种经典矛盾。实际上问题在于：你的本地检查链根本没有形成闭环。t3code把"本地提交前检查"和"CI全量检查"放在同一套命令下，降低环境差异导致的返工。

1.2 t3code的设计理念：一次配置，在三个环节自动生效

这套方案的核心理念可以概括成一句话：规范必须落到机器上，不能只写在Wiki里。写文档当然有作用，但文档不会阻止你提交有问题的代码。t3code的思路是建立三道防线：

• 第一道防线在编辑器里，提供统一的格式化配置和ESLint提示，开发者写代码时就能看到问题；
• 第二道防线在提交前，借助husky和lint-staged，只检查本次改动的文件，速度足够快，不打断开发节奏；
• 第三道防线在CI阶段，执行全量检查，防止有人绕过本地钩子，也防住某些特殊情况（比如本地跳过检查的-force提交）。

这三道防线并不是把同样的命令重复跑三遍，而是各有侧重。编辑器负责即时反馈，Husky负责低成本拦截，CI负责最终兜底。配置做成共享包之后，无论新老项目都能复用同一套规则，团队成员不需要在多个项目里记住不同的检查命令。

工具选型上，我也没有引入太高门槛的东西。ESLint依然是社区事实标准的JavaScript/TypeScript检查工具，Prettier负责风格格式化，TypeScript自带的编译器在严格模式下做类型检查，Husky负责挂接git钩子，lint-staged控制只检查暂存文件。每个工具解决一个明确的问题，不叠加复杂度。在此基础上，又用commitlint约束了提交信息格式。你会发现，这套组合里没有冷门工具，全是经过大规模项目验证的成熟选择，这正是t3code比较稳妥的一点。

2. 核心能力拆解与工具选型背后的逻辑

2.1 编码规范检查：为什么ESLint仍然是绕不开的核心

ESLint在这套体系里承担的是"规则裁判"角色。它不负责排版，重点关注的是代码中潜在的问题：未使用的变量、可疑的空值访问、不合规的Promise处理、TypeScript相关的类型误用等。你可能会说"我代码写得对不就行了"，但ESLint能捕捉到很多肉眼不容易发现的坑。

t3code里的ESLint配置并非我临时拼出来的，而是在typescript-eslint推荐规则集的基础上，结合团队实际踩过的坑做的取舍。比如禁用了any的隐式使用、强制函数显式声明返回类型、禁止使用废弃API等。这些规则初看觉得"严格"，实际跑起来会发现它逼着你写出更好维护的代码。我调试过一个线下bug，追踪到根因就是某个接口字段被当成了string用，但实际可能是undefined。ESLint并不会直接抓住这种逻辑错误，但它在类型层面引发的连锁警告，往往会成为排查思路的起点。

选型时要解释清楚一个原则：ESLint只管规则，不管格式。很多新手配置时会把缩进、引号、分号这些格式规则也写进ESLint，再和Prettier一叠加，两边规则冲突，跑一次检查报几百个红。这种问题根子出在职责不清。正确的姿势是：ESLint管逻辑规范性，Prettier管代码排版，两者通过eslint-config-prettier关掉ESLint里与格式化重叠的规则。分工明确之后，规则冲突会大大减少，配置也更容易理解。

2.2 代码格式统一：Prettier的意义在于"放弃争论"

Prettier的价值不在于它生成的风格是史上最好看的，而在于它能终结争论。它提供一套完全确定性的输出规则：同样的输入代码，永远输出同样的格式结果。团队成员根本不需要去记住"什么时候该换行、什么时候该加括号"，保存文件时prettier会自动处理。最理想的状态是，每个人本地保存自动格式化，配合编辑器里"format on save"，整个仓库的代码风格会迅速收敛。

t3code里我推荐在项目根目录放一份独立的.prettierrc，例如统一使用单引号、行宽100、结尾不加分号。这些参数没有绝对的对错，核心诉求是团队认可并长期一致。之前有一个项目没有固定行宽，部分同事习惯写很长的一行再靠prettier自动折行，部分同事写两行，结果每次改动diff范围都很大。定下行宽和引号风格之后，这几个文件的diff干净清爽，review效率肉眼可见地提升。

有一点要特别提醒：Prettier最好设置为"唯一格式化来源"。我见过有项目同时使用Stylelint、ESLint里嵌套的format规则、编辑器的默认格式化工具，最终效果互相打架。t3code的规则是，非代码文件也一样交给prettier处理：json、markdown、yaml、css、less都可以统一。这样可以避免"代码风格统一了，配置文件还是五花八门"的半吊子状态。

2.3 类型安全与测试兜底：TypeScript严格模式和Vitest跑起来

如果代码风格只是"外观"，那类型安全就是"骨架"。t3code里的TypeScript并不停留在"用了ts就是安全"这种自我安慰上，而是直接启用严格模式："strict": true，再配合tsc --noEmit作为独立的类型检查命令。为什么不用build来顺带检查？因为真实的构建命令里可能有babel、webpack、vite等一系列编译步骤，报错信息被吞掉或者被警告淹没，没人会盯着看。把类型检查拆成独立步骤后，CI的日志里能清清楚楚看到："类型错误：第X行，类型string不能赋值给number"。这个排查路径比翻构建日志高效太多。

单独跑tsc --noEmit还有一个好处，它不产出任何构建文件，纯粹是验证类型，速度会更快，也更适合作为本地提交前检查的一部分。至于单元测试，t3code选了Vitest而不是Jest，原因是Vitest在TypeScript和ESM项目里配置成本更低、启动速度更快，日常开发体验更顺滑。测试不是摆设，至少要确保工具函数、公共组件、复杂状态逻辑这些核心模块有测试保护。在t3code的check链路里，测试失败同样会阻止提交。

这里想强调一下"为什么要把类型检查和单测放进提交前钩子"。很多团队的教训是：检查和CI解耦，开发者本地跳过了问题，等CI跑完再通知你失败了，一个来回就是十几分钟甚至更久。放在本地提交前执行，虽然每次commit会多消耗几秒，但能把大部分低级问题拦截在提交之前，这种投入非常值得。

3. 从零落地t3code：完整配置与实操细节

3.1 初始化脚手架：依赖安装与目录规划

在动手配置之前，先规划一下项目的目录结构。t3code会引入config、scripts、hooks三块内容，我建议是：

project-root/ .husky/ pre-commit commit-msg scripts/ check.sh .eslintrc.cjs .prettierrc vitest.config.ts package.json

安装依赖时，直接一次性装齐基础包。以npm为例：

npm install -D eslint prettier typescript husky lint-staged @typescript-eslint/parser @typescript-eslint/eslint-plugin eslint-config-prettier vitest commitlint @commitlint/cli @commitlint/config-conventional

装完之后，先把package.json里的scripts配置成t3code的标准命令模板：

{ "scripts": { "lint": "eslint . --ext .ts,.tsx", "lint:fix": "eslint . --ext .ts,.tsx --fix", "format": "prettier --write .", "typecheck": "tsc --noEmit", "test": "vitest run", "check": "npm run lint && npm run typecheck && npm run test" } }

这个npm run check就是t3code链路的核心聚合命令。它的执行顺序是有讲究的：先跑lint，再跑类型检查，最后跑测试。因为lint出问题通常是低成本修改，类型问题其次，单测失败可能需要打开调试器慢慢排查。先快后慢，能让你拿到最快的反馈。

接着看ESLint配置。如果项目还在用传统的.eslintrc.cjs格式，可以按下面这样组织：

module.exports = { root: true, parser: '@typescript-eslint/parser', parserOptions: { ecmaVersion: 'latest', sourceType: 'module', }, plugins: ['@typescript-eslint'], extends: [ 'eslint:recommended', 'plugin:@typescript-eslint/recommended', 'prettier', ], rules: { '@typescript-eslint/no-explicit-any': 'error', '@typescript-eslint/explicit-function-return-type': 'off', '@typescript-eslint/no-unused-vars': ['error', { argsIgnorePattern: '^_' }], }, ignorePatterns: ['dist', 'node_modules', 'coverage'], };

如果是从零开始的ESLint 9项目，官方推荐的flat config写法是导出一个配置数组，但规则的思路完全一致。这里我不啰嗦两种格式的细节差异，只提醒一点：不管用哪种格式，prettier必须放在extends的最后，否则它关不掉ESLint里格式相关规则的冲突。很多人在这一步踩坑，规则加载顺序反了，导致格式规则冲突。

Prettier配置就比较简单，我常用的版本是：

{ "semi": false, "singleQuote": true, "printWidth": 100, "trailingComma": "es5", "tabWidth": 2 }

这些参数是经验值吗？是，但并不全是。printWidth设为100是为了兼顾可读性和行数；singleQuote纯粹是团队选择；no semi是我个人偏好的极简风格，如果你的团队习惯分号，直接改成true就行。关键不是用哪一套，而是固定下来不要变。

3.2 提交前自动校验：husky与lint-staged的配合

安装完husky之后，需要手动执行一次初始化命令：

npx husky init

这条命令会在项目根目录创建.husky/文件夹，并准备一个pre-commit钩子。第一次配置时，把默认生成的钩子内容替换成lint-staged的调用：

npx lint-staged

然后在package.json里添加lint-staged配置：

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

为什么要用lint-staged而不直接在钩子里跑npm run check？因为项目一大，全量lint和typecheck可能要跑几十秒，每次commit都等这么久，团队很快就烦了，然后有人就开始批量绕过钩子。lint-staged只处理当前暂存区里被git标记为改动的文件，范围小，速度快，一般一两秒内结束。这才符合"低摩擦"原则：在Pre-commit阶段，检查速度必须足够快，才有人愿意长期用。

这里有几个非常关键的操作细节。第一，eslint --fix和prettier --write是会对文件做修改的，修改后lint-staged会自动把改动重新放入暂存区，所以不必手动git add。第二，如果你在执行过程中看到"some files were not formatted properly"之类的提示，先检查是不是.prettierrc里的配置和项目里已有文件的风格不一致，把存量文件先格式化一遍再提交。第三，lint-staged里不要混入typecheck和test这两个重命令，它们应该留在pre-push钩子或者CI里，否则每次commit都会很慢。

commit信息规范我同样放在提交钩子里。.husky/commit-msg文件里写：

npx --no -- commitlint --edit $1

再配合@commitlint/config-conventional，提交信息就会被约束成feat: xxx、fix: xxx、docs: xxx这类约定式格式。刚开始团队成员可能不太习惯，但坚持几周后，git log会变得极其清晰，回溯bug时能直接看到某次提交的意图，release changelog也可以基于这些commit信息自动生成。这一步成本极低，收益却是长期的。

3.3 CI流水线里的完整校验链路

本地钩子毕竟是本地环境，有人如果用了--no-verify绕过钩子，或者某些改动在特定环境下才会暴露问题，最终防线还是CI。t3code在CI里的做法很简单：跑一次完整的npm run check，再加上commitlint校验和构建命令。以GitHub Actions为例，一个精简的workflow长这样：

name: code-check on: push: pull_request: jobs: check: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: actions/setup-node@v4 with: node-version: 20 cache: npm - run: npm ci - run: npm run lint - run: npm run typecheck - run: npm run test - run: npm run build

如果你是GitLab CI或者自建流水线，核心就是串联这几条命令。注意这里我没有直接用npm run check，而是把lint、typecheck、test拆开执行，这么写的目的很直接：CI的日志需要分段清晰，哪一步挂了一目了然。如果全塞进一个命令，失败日志只会告诉你是check挂了，还得重新点开看细节，排查成本反而变高。

还有一点我从实践中得出的经验：CI里的依赖安装尽量用lockfile。无论用npm ci、yarn --frozen-lockfile还是pnpm install --frozen-lockfile，目的是保证CI和本地安装的依赖完全一致，避免"本地测过没问题、CI上用新版本依赖突然报错"这类问题。在Node工程里，依赖版本漂移引发的构建不一致，我见过不止一次，而且排查起来非常恶心。

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

4.1 规则冲突与配置文件优先级

最常见的问题是：明明安装了Prettier，也配置了ESLint，可是eslint执行时还是会报格式错误。原因一般是ESLint里还有格式规则没有被关闭，比如indent、quotes、semi。我在团队推广t3code时遇到过两次类似问题，都是因为配置文件里prettier没有放在extends的末尾，或者用的不是eslint-config-prettier而是旧的eslint-plugin-prettier。

eslint-plugin-prettier这种方案是把prettier当作eslint的一条规则来跑，代码不规范时它会以eslint error的形式报出来。早期一些项目喜欢这么干，实际体验是每次保存文件都要靠eslint --fix去处理格式，速度慢，而且它的报错信息满屏红字，很打击人。t3code采用的方案是职责分离，eslint不管格式，prettier单独处理。配置里其实只需要extends加上prettier即可。

如果遇到某个规则"顽固"地报错，排查方法也很简单。在项目根目录执行：

npx eslint --print-config src/index.ts

这条命令会打印当前文件最终生效的所有规则，你能直接看到某个规则是开启了还是关闭了，以及它是由哪个配置项引入的。有次排查一个"no-explicit-any"警告始终消不掉，用这个命令一查，发现是某个第三方插件里自带的开规则叠加，调整一下plugins顺序和rules覆盖就解决了。

4.2 类型检查慢与内存占用大

tsc --noEmit在项目变复杂之后可能会慢，尤其是大量第三方类型定义和没有做增量缓存的情况下。t3code里我针对这个问题的处理办法有三招。

第一招是在tsconfig.json里开启"incremental": true并指定tsbuildinfo文件，第二次及以后的类型检查会复用上次的增量信息，速度提升明显。第二招是开启"skipLibCheck": true，跳过.d.ts文件的类型检查，这里要说明的是，它并不会影响你业务代码的类型安全，只是不再逐个检查node_modules里的声明文件。第三招是排除不必要的目录，比如dist、coverage、node_modules都放到exclude里。

内存占用方面，如果CI里跑tsc时经常OOM，可以给Node设置更大的内存上限：

node --max-old-space-size=4096 node_modules/typescript/bin/tsc --noEmit

或者在scripts里写成"typecheck": "node --max-old-space-size=4096 node_modules/typescript/bin/tsc --noEmit"。实测在大型仓库里，这样能省去很多"CI构建说内存不够"的空转时间。

4.3 团队推广时的三个现实阻力

工具层面的问题往往不是最难解决的，更难的是让人愿意用。我在带着团队落地t3code的时候，阻力主要是三类。

第一类是"新配置影响了我的开发习惯"。最常见的抱怨是"为什么我保存文件时多加了一个分号也要被报错？"解决方式不是讲大道理，而是给出一个明确的规矩：全组统一用prettier的格式化风格，并在编辑器里开启format on save。只要大家都这么设置，实际开发过程中几乎不会有格式冲突，报错自然变少。我在团队wiki里放了一份prettier插件安装说明，五分钟能解决环境下的一致性问题。

第二类是"某个老文件改动后，lint报了一堆陈旧错误"。这是存量代码改造时最实际的痛点。t3code的策略是：先做一次全量格式化，把存量文件的格式问题一次性解决，再针对lint规则里比较严重的error手动修一轮。少量无法立刻处理的规则先降为warning，但设定一个迭代期限，逐步清零。一刀切全修，容易让团队抵制；全不管，形同虚设。折中方案才能顺利过渡。

第三类是"提交前跑了check，速度太慢"。#如果是项目很大，lint-staged阶段别放重量级检查，把重检查留到CI。如果husky钩子在部分Windows机器上不执行，先检查core.hooksPath是否被全局工具改过，或者看git version和node版本是否过老，必要时可以让负责基建的同事统一升级环境。

4.4 常见问题速查表

这些是t3code实际运行中大半年收集到的真实问题，其中一半是我自己踩过的坑，另一半来自团队成员的反馈。你会发现绝大多数问题并不复杂，但如果没有见过，第一次遇到时还是会慌一下，排查上十几二十分钟。有一个规律我体会很深：自动化检查链路的维护成本不在配置本身，而在"规则变更"和"环境差异"两件事上。规则变更需要走团队评审，不要某个人悄悄改了共享配置；环境差异最好用统一版本的Node和包管理器来收敛。

5. 一点额外的实践经验：把t3code沉淀成共享配置

项目跑通只是第一步，真正让这套东西发挥长期价值的是把它抽成共享配置包。我在t3code里的做法是维护一个单独的npm包，比如@team/t3code-config，把.eslintrc.cjs、.prettierrc、commitlint配置、vitest基础配置全都放进这个包里。新项目初始化时，直接安装这个包，引用预设规则，一分钟就能接入整套检查链路。

这么做的好处非常明显。第一，规则修改只需要在共享包里改一次，所有项目同步生效，不需要逐个仓库手动更新。第二，新成员入职后，配置成本极低，他不需要理解每个规则从哪来，只需要记住npm run check这一个命令。第三，跨项目之间的一致性会加强，你从A项目切到B项目时，不用重新适应一套完全不同的代码风格。

共享包的具体结构可以这样做：

t3code-config/ src/ eslint.base.cjs prettier.base.json commitlint.base.cjs vitest.base.ts index.cjs package.json

引用时，项目侧只要把extends改成指向这个包导出的配置文件即可。当然，这里不强制要求所有项目百分百共享同一套规则，特殊项目可以在引用后覆盖单个规则。但默认配置必须是统一基线，例外永远走评审流程。

我给你一个很具体的建议：先别急着把规则定得面面俱到，让规则随团队真实踩坑逐步累积。刚开始只保留recommended和prettier，再添加团队实际遇到的三五个核心规则。跑两周之后，大家习惯了，再根据review里反复出现的低级失误，把对应的规则加进来。这样每一条规则都有真实场景背书，推动时阻力最小。反过来，如果第一天就塞进去上百条自定义规则，团队成员会被满屏红字劝退，最后这套体系就只剩CI服务器自己在运行，实际开发时没人认真对待。

最后再分享一个小技巧：把npm run check设定为pre-push钩子。pre-commit只处理本次改动的文件，保证的是质量和速度的平衡；pre-push做一次全量check，保证推到远端的分支是经过完整验证的。两道闸门的节奏不同，但效果互补。我见过有的团队只在commit钩子里做全量检查，每次提交要等一分钟，然后又因为太慢而全部绕过。正确的夹具是：重检查放到push之前，轻检查留在commit之前，这样才能既保体验又守底线。

t3code这套东西，说难不难，说简单也不简单。它本质上不是某个惊艳的技术，而是一套可靠的工程纪律，用工具把约定固化下来，减少人和人之间无谓的争执。如果你现在还在为代码风格和review争议头疼，不妨按这个思路搭一遍，跑一个月再回头看，团队的整体节奏会有很明显的变化。