企业官网建设流程全解析

t3code这个代号，在我手里已经用了大半年。起初它只是我临时起意给一个内部命令行工具起的名字，用来解决一个特别具体的问题——团队里每次开新业务模块，都要从旧项目里复制一大堆初始化代码，再改包名、改路由、改接口前缀，稍不注意就漏改一处，上线前炸出来一堆低级问题。

后来这个代号越用越广，从最初一个人的小工具，慢慢变成了团队代码初始化、依赖安装、质量校验的标准入口。这篇文章就把我这一年多来围绕t3code做的所有事、踩过的所有坑、沉淀下来的经验完整记录下来，给同样在做前端工程化、脚手架、代码模板治理的朋友一个参考。

1. t3code到底是什么：一个内部代码脚手架的自白

1.1 项目名的由来

先说名字。t3code这个代号，最初不是深思熟虑的产物，而是我手里一个实验性项目的临时文件名。t3取自“Turbo Template Toolbox”的缩写，本意是做一个快一点的模板工具箱，后来简化到只剩三个核心命令：init、generate、check，也被团队里调侃成“三条命令走天下”，t3就这么阴差阳错地保留了下来。

很多人在自己的脚手架项目里纠结叫什么名字，我的建议是别在命名上花太多时间。项目名只要好记、不和社会上已有的开源项目冲突，就先跑起来再说。真正让一个代号有价值的是它背后的使用逻辑，而不是名字本身。

1.2 它到底解决了什么问题

t3code真正解决的问题，从表面上看是“代码初始化太慢”，但往深了说是三个层面的问题。

第一层是复制粘贴带来的基线漂移。团队里只要靠人肉复制旧项目来开新模块，就一定会出现每个项目的初始化代码长得都不一样的情况。今天张三多写了一个工具函数，明天李四删掉了一个废弃依赖，三个月后再去看，所有业务模块的底层结构已经面目全非。这种无规律的差异是后期维护最恶心的事情。

第二层是代码风格不统一带来的review噪音。一份PR里如果大量改动都集中在缩进、引号、命名格式上，真正需要review核心逻辑的人就必须在一堆格式改动里大海捞针。t3code把生成代码的格式提前标准化，从根源上消除了这类噪音。

第三层是新成员的上手成本。团队里有新人进来，第一件事往往就是找老同事要“上次那个项目的代码”。有了t3code之后，新同学只要一条命令就能生成一个完整的、结构符合规范的、带好基础配置的代码骨架，然后在这个骨架上改自己的业务逻辑。上手周期从一两周压缩到一两天，这个体感是非常明显的。

1.3 适合谁读、怎么读这篇分享

如果你是在团队里负责前端基础设施、脚手架或者工程化治理的工程师，这篇文章可以直接当作业抄。

如果你是刚接触工程化概念、想搞明白“代码模板治理到底在干什么”的初级开发者，我会尽量把原理讲得通俗一些，你会知道那几条命令背后到底发生了什么事情。

如果你是技术管理者，想评估这类工具对团队效率的影响，文里的实操过程和数据复盘部分值得重点看。

读的时候不用从头到尾一次读完。你可以先看第3章的实操，跟着命令走一遍，然后回头补第2章的设计思路，最后再看第4章的坑，这样理解起来最顺畅。

2. 技术方案与设计思路：从手写模板到三条核心链路

2.1 为什么做成CLI而不是可视化平台

t3code在最初设计的时候，摆在面前的有三条路：做一个带网页界面的可视化配置平台、做一个基于VS Code插件的图形化工具、做成纯命令行CLI。

我最后选了CLI，核心原因有三个。

第一个原因是可脚本化。CLI可以被Git Hook、CI流水线、提效脚本无差别调用。比如团队在Git提交前自动执行一次t3code check，这种能力可视化平台很难做到。代码生成这个动作天然需要嵌入到研发流程里，CLI是整个链条中最容易嵌入的形态。

第二个原因是开发成本可控。可视化平台需要额外的前端界面、后端存储、权限系统，初期投入至少要比CLI多三倍。而在一个内部工具上，我们最需要的是快速试错、快速迭代，CLI足够满足需求。

第三个原因是使用路径足够短。开发者开新页面时，痛点往往就是“别让我在工具里点来点去”，一条命令搞定所有事情才是真实的预期。生活里你去银行办业务，如果大堂经理给你一张表让你自己填完再排队，你一定觉得麻烦，但如果是扫码自助填单然后直接叫号，体验就顺多了。CLI就是那个“扫码自助填单”。

2.2 三条核心链路的设计拆解

t3code的内部结构，我拆成了三条相互独立的链路：模板解析链路、依赖安装链路、质量校验链路。三条链路各自做各自的事，通过统一的配置文件和中间产物衔接，互不耦合。

模板解析链路是整个工具的地基，负责读取本地模板目录、识别占位符、渲染出最终的目标文件。我选用了EJS作为模板引擎，理由很简单：语法接近已经普及的HTML/JS，团队里多数人看一眼就能上手。模板里通过<%= name %>插入变量，通过<% if (...) { %>做条件判断，学习成本几乎为零。

依赖安装链路负责在生成代码后，根据模板携带的package.json自动执行依赖安装。这里有个关键设计决策：不强行全局安装，而是生成一个锁文件，然后调用项目本地的包管理器。这样既保证了不同机器上的安装一致性，又不会让t3code过度侵入开发者本机的全局环境。

质量校验链路是很多人容易忽略、但恰恰是t3code价值密度最高的一环。它在生成结束后自动跑一遍lint、类型检查、配置文件校验，把潜在问题直接挡在文件落盘之前。这个环节在后面第3章里有详细展开。

三条链路的依赖关系是单向的：解析完成之后立即进入校验，校验通过后才开始安装依赖。这样设计的初衷是避免无效安装，如果模板解析出来代码本身就是错的，那依赖装得再快也没有意义。

2.3 核心选型：模板引擎、配置模型与AST解析

选型阶段我在模板引擎上做过几个候选对比，这个表你可以直接保存。

另一个容易被忽略的点是AST解析。在生成文件之后，单纯做文本级的替换是不够的，因为代码不是字符串，是一个需要有结构的对象。比如生成的TS文件里，import顺序混乱、某个变量命名没有遵循camelCase规范，这在文本层面根本看不出来，必须靠AST层面去识别和修正。

我在t3code里集成了一个轻量的AST检查流程：对生成的每个TS/JS文件，先parse成语法树，然后做三个检查——导入语句是否按字母顺序排列、导出的实体命名是否符合项目规范、是否存在声明了但从未使用的变量。前两个问题自动修复，第三个问题直接报错，让开发者自己决定是删掉还是补上使用逻辑。这一层检查虽然增加了一点运行耗时，但换来的收益是它的产物从一开始就在“风格正确”的轨道上。

2.4 配置模型：一份配置文件管全部

模板目录、变量清单、校验规则、依赖源，所有这些集中到一个t3code.config.js里。这段配置看起来大概是这样：

module.exports = { templatesDir: './templates', outputDir: './src/modules', variables: { projectName: { type: 'input', required: true }, moduleName: { type: 'input', required: true }, language: { type: 'select', options: ['ts', 'js'], default: 'ts' } }, hooks: { beforeRender: './hooks/beforeRender.js', afterRender: './hooks/afterRender.js' }, check: { eslint: true, tsc: true, ast: { importOrder: true, naming: 'camelCase' } } }

这个配置模型的妙处在于它把“模板”和“配置”分离了。模板里只写哪些地方需要插入变量，不写变量的值从哪里来；配置里只声明变量的规则，不关心模板长什么样。有了这层隔离，团队里的一个同事可以只改模板不动配置，另一个同事可以只调规则不碰模板，互不干扰。

我强烈建议你把hooks这个字段用起来。它允许你在渲染前和渲染后插入自定义逻辑，比如在生成前检查目标目录是否已存在同名文件、在生成后自动打开本地开发服务。这个设计让我在后来的很多扩展性需求里都没改过主框架代码，只需要写一个小hook。

3. 实操全过程：从零搭建一个t3code项目

3.1 安装与初始化

安装命令很简单，文档里写的是全局安装，但我在内部更推荐用npx来跑，这样每个项目都拉到自己对应的版本，不会因为全局包版本不一致导致生成结果差异。

npm i -g t3code # 或者用 npx 避免污染全局环境 npx t3code init my-project

init命令会做几件基础工作：创建一个基础目录骨架、生成一份默认的配置文件、拉取一套官方基础模板到本地。完成后的目录结构长这样：

my-project ├── templates/ │ ├── module/ │ │ ├── __name__.ts.ejs │ │ ├── __name__.test.ts.ejs │ │ └── index.ts.ejs ├── hooks/ │ ├── beforeRender.js │ └── afterRender.js ├── t3code.config.js └── package.json

注意看模板文件名的写法：__name__.ts.ejs。这个设计是我故意做的，__name__会在生成阶段被替换成用户传入的模块名，而.ejs后缀只表示这是一个模板文件，真正的产物在渲染后会变成order.ts这样的文件。这种命名方式让文件名里的变量一目了然，不用去读模板内容就能猜到生成效果。

3.2 自定义一个业务模板

我们自己团队用得最多的是一套“带标准CRUD接口的业务模块”模板。为了讲得具体，我用一个订单模块来演示。先在templates/module/目录下建三个文件。

第一个是核心业务文件模板__name__.ts.ejs，内容大致如下：

import { defineModule } from '@/core/defineModule' import { <%= name %>Service } from './<%= name %>.service' export const <%= name %>Module = defineModule({ name: '<%= name %>', routes: [ { path: '/<%= name %>/list', handler: <%= name %>Service.list }, { path: '/<%= name %>/detail', handler: <%= name %>Service.detail } ] })

第二个是测试文件模板__name__.test.ts.ejs：

import { describe, it, expect } from 'vitest' import { <%= name %>Module } from './<%= name %>' describe('<%= name %>Module', () => { it('should have list route', () => { expect(<%= name %>Module.routes[0].path).toBe('/<%= name %>/list') }) })

第三个是统一出口index.ts.ejs：

export * from './<%= name %>' export * from './<%= name %>.service'

配置好变量清单之后，执行生成命令：

t3code generate module --name=order

你会在src/modules/下看到生成好的order.ts、order.test.ts、index.ts三个文件。如果此时目标目录里已经有同名文件，t3code会停下来问你而不是直接覆盖，这个交互细节在后面第4章的坑里还会专门讲到。

跑通这一步之后，你可以试着改模板里的内容，比如在路由数组里加一个detail接口，或者在defineModule参数里加一个meta字段，然后重新生成一个新模块名，观察输出差异。这种改一次模板、生成多个模块的用法，是t3code最核心的价值所在。

3.3 生成后的质量校验链路闭环

生成完成不等于事情结束了，t3code会紧接着自动执行质量校验。这一步是我觉得整个工具最值得抄的设计。

校验链路分三个层次。第一层是模板渲染本身是否合法，比如EJS语法有没有写错、占位符是否闭合。第二层是AST级别的检查，对生成出来的TS文件做语法解析，不通过的直接给出具体错误位置。第三层是调用项目里已有的ESLint和TypeScript检查程序，用团队现有规则做最终裁决。

我在实际使用中加入了这样一个配置：

{ "check": { "eslint": true, "tsc": true, "ast": true } }

更进一步的玩法是把校验接进Git Hook。团队目前的做法是：在pre-commit钩子里加一行t3code check，这样任何未经校验的手改代码也会被拦下来，相当于把校验链路从“生成时”延伸到了“提交时”。实测下来，这条路能拦掉大概三成因为手改配置而引入的奇怪错误。

4. 踩坑实录：我在t3code实战中遇到的5个典型问题

4.1 模板变量命名不规范导致生成失败

第一个坑是变量命名。有一段时间团队里写的模板变量名极其自由，有人用{{ orderName }}，有人用<%= order_name %>，还有人直接在模板里写死字符串不想改。

EJS本身对变量名是宽容的，问题出在后面AST层做命名规范检查时。我之前把规范设定为camelCase，结果一批用下划线风格的模板全部校验失败。

排查了很久才定位到问题根源：模板层允许自由命名，校验层又强制规范命名，两层之间缺少一个映射机制。后来我把变量声明收敛到配置文件的variables字段里，同时增加了一个提示逻辑——在渲染阶段捕获所有用到的变量，凡是没有在variables里声明的，直接列出警告。这样就逼着写模板的人先把变量名在设计阶段定好，而不是随手写进渲染句法里。

现在我的统一约定是：所有模板变量一律使用lowerCamelCase，变量声明只在t3code.config.js里出现一次。如果你去翻现在团队里的模板代码，会发现__name__、__service__这类命名已经完全统一了。

4.2 路径计算在多级目录下失效

模板文件里经常需要引用相对路径，比如从src/modules/order跳回src/core，要写../../core/xxx。这个看起来简单，但一旦模板嵌套层级变深，或者输出目录结构调整，路径就会瞬间崩掉。

我第一次遇到这个问题是在一个生成“三级嵌套业务模块”的场景里。模板里写的../../common在测试环境下是好的，但实际部署时模板被放到src/modules/business/order下面，相对路径就少了一层，生成的引用直接指向不存在的目录。最气人的是这个错误不会在EJS渲染时报出来，只有等到运行时才能发现。

解决方案很简单但很有效：把输出路径彻底改成以项目根目录为基准的绝对路径。模板里不再写相对路径，而是统一使用一个@别名来表示src/目录，生成时通过t3code读取项目的tsconfig配置，把@替换成对应的真实路径。这个改动一次性解决了所有层级嵌套问题，还顺手统一了团队里import路径的风格。

4.3 手写模板时不小心破坏YAML结构

团队里有好几个模块需要同步生成GitLab CI的配置文件，所以t3code模板里也有.gitlab-ci.yml.ejs。这个模板看起来很简单，无非就是把一些重复的job配置抽出来，但实际用起来特别容易出事。

EJS渲染是逐行文本替换，如果你在<%= deployType %>这种指令后面多打了一个空格，或者在缩进时用了TAB而不是空格，渲染出来的YAML就会语法报错。YAML对缩进极其敏感，一个空格错位就能让整段CI配置失效，而且报错信息往往只是干巴巴的一句invalid mapping。

我还遇到过更隐蔽的情况：模板里某个变量在运行时是空字符串，导致渲染结果直接少了一行配置，下面所有配置的层级整体上移，变成了一堆看起来像配置但压根不生效的垃圾。

这个问题没有特别完美的根治方案，我目前的处理方法是：对所有涉及YAML的模板，在渲染后追加一步YAML语法校验。版本更新后新增了一个yamlLint选项，默认开启，不通过就报错。这个检查成本很低，但避免了很多次深夜调试CI的惨痛经历。

4.4 增量更新时的覆盖冲突

到了中后期，大家不再满足于用t3code生成全新模块，开始有人试图用它来批量改造老项目。这就遇到了增量更新的问题：老项目里已经存在相同路径的文件，直接覆盖肯定不行，但完全不处理又达不到升级的目的。

我第一版实现非常粗暴——发现同名文件就报错退出，让用户手动处理。结果被同事吐槽“工具不够智能”，一次改造要反复切换终端和编辑器。后来我改成了现在的策略：默认进入diff模式，对已有的同名文件生成一个临时对比文件，用终端里的diff工具展示差异，由用户决定是覆盖、跳过还是合并。加了一个--force参数用来显式跳过提示，但我明确建议不要默认使用它，因为历史教训太多了。

这个改进被用了大概一个月后，团队里基本形成了默契：重度改造时用--force跑一遍，然后立刻跑t3code check做校验，相当于用后端校验弥补了前端拦截的缺失。

4.5 循环生成时的context污染

t3code支持批量生成，比如给一个配置数组里循环调用生成命令。这个功能上线后没多久，有人反馈说连续生成两个模块时，第二个模块的名字总是第一个模块的名字。

排查了一整天，最后定位到一个特别蠢的错误：我在主流程里复用了同一个context对象，循环调用时没有深拷贝，第二次生成时就把上一次的name字段改掉了。EJS渲染是在原有对象上做修改的，看起来一切正常，但一旦第二次渲染读取了已经变更的字段，就全部乱套。

修复只需要一行代码：在每次生成前对context做一次深拷贝。问题虽然蠢，但暴露了一个通用教训——任何会重复执行的代码，都必须格外警惕共享状态的污染。这个坑在写通用工具时非常典型，建议所有做脚手架的同学都记在心里。

4.6 常见问题速查表

5. 实战效果：从效率数据到后续扩展

5.1 数据复盘与实际体感

项目推进到现在，团队里所有新业务模块的初始化已经100%经过t3code。我抽空统计了一下几个关键数据：原来手写一个带CRUD接口的标准模块，从抄代码到改完配置、写完类型定义、跑通测试，大概需要45分钟到1小时；现在一条命令生成后，整体耗时压到了3到5分钟。

Review数据更加直观。改造之前，一份初始化代码的PR平均要修改15到20个文件，里面大量是重复性的格式微调；现在大部分PR只有一个文件，就是业务模块自己的逻辑代码，review时长从平均40分钟降到了10分钟左右。这不是我一个人的感受，团队里另外几个核心开发都有类似的体感反馈。

新人上手速度是另一个隐性收益。之前带新人走一遍“看项目结构、理解初始化流程、手动搭一遍环境”的流程，大概要一周；现在t3code init之后，新人自己就能在模板基础上改出第一个可运行的业务模块，老的初始化宣讲PPT基本退休了。

5.2 接下来的扩展方向

t3code现在能满足绝大多数生成场景，但扩展空间还有很多。我这里列三个正在考虑的方向。

第一个是模板市场。目前模板都存在本地仓库，团队之间共享需要手动拷贝。计划做一个私有模板仓库，支持按标签检索、一键拉取，不同团队可以维护各自的模板，但基础规范模板由核心维护组统一管理。

第二个是生成后可交互编辑。当前命令行的交互只覆盖变量输入，生成结果如果想微调，需要开发者手动改文件。后续可以在生成后提供一个“预览改动”的交互式界面，类似git add -p那种逐块确认的模式，让增量改动更顺手。

第三个是把校验能力从“文件内”扩展到“跨文件”。比如两个模块之间是否有循环依赖、接口定义是否冗余，这类跨模块的检查目前t3code还没覆盖。这部分一旦补上，它就从一个代码生成器进化成代码结构治理工具了。

我最后再说一个实操小技巧：如果你们团队的模板也在快速演进，别急着把所有模板都收录进t3code。先在业务代码库里留一个_preview目录，把待定的模板放在里面，跑几轮真实需求后再正式转正。这样既能持续迭代模板质量，又不会让不成熟的模板污染主要生成链路。这套玩法延续了快半年，效果稳定，值得一试。