企业官网建设流程全解析

做了几年全栈开发，最让我头疼的从来不是某个刁钻的业务逻辑，而是新项目启动时那套机械重复的初始化流程——建目录、配 tsconfig、装依赖、写接口骨架、搭数据库连接。t3code就是在这个背景下冒出来的一个命令行工具，定位是面向 TypeScript 全栈项目的代码生成与脚手架方案。它做的事情本身不复杂：用一个配置文件描述项目结构，再用模板渲染的方式把可运行的代码骨架批量生成到磁盘上。如果你也受够了每次开新模块都复制粘贴旧代码，或者团队里每个人写出来的接口风格都不太一样，这篇文章应该能给你一些参考。

坦白说，这个工具早期只是我自己用的脚本，后来在几个实际项目里迭代过几轮，才逐渐变成现在这个结构清晰、可自定义模板的形态。下面我会从设计思路讲起，把核心原理、实操流程、模板扩展方式和踩过的坑都摊开来说，保证你读完不仅能理解它的工作方式，还能顺手改造成自己团队的那一版。

1. 从"复制粘贴"到"敲一条命令"：t3code 解决的痛点

1.1 重复劳动的真实成本

开一个新项目，通常意味着什么？先拷贝一份旧项目的目录，删掉业务代码，保留配置；接着全局搜索替换包名；然后手动创建 controller、service、model，每个文件都要维护同样的 import 路径和注释头；最后还要处理数据库连接、日志配置、鉴权中间件。这一整套流程，熟练的话要 40 分钟，不熟练的话半天就没了，而且极其容易遗漏某个配置文件。

你可能觉得 40 分钟不算长，但问题在于它不是一次性的。每个月新起 2 个内部工具项目，每个项目 3 个模块，每个模块按 4 个文件算，你一个月就在机械操作上消耗掉大半天。更麻烦的还不是时间，而是不一致——同一个路由命名风格，上个月写的是camelCase，这个月新来的同事用了snake_case，代码评审的时候为这种破事来回扯皮，才是最亏的。

t3code的思路很直白：把"项目结构"变成一份可版本化的配置文件，把"代码风格"沉淀成模板文件，然后通过命令行一次性产出完整、可运行的骨架代码。你要做的只是描述"我想要什么"，至于"代码长什么样"由模板决定。

1.2 为什么选择做 CLI 而不是直接复制模板

市面上已经有很多脚手架工具，比如create-next-app、create-t3-app，它们能做整站初始化。但实际工作中我发现一个空白：整站脚手架解决的是"从一个项目到另一个项目"，而日常开发大量需求是"在一个项目里新增一个模块"。

整站脚手架用起来太重了。我只想加一个带 CRUD 的user模块，却必须回到项目初始化阶段重新跑一遍，这显然不合理。t3code在设计上一开始就走了一条不同的路：既有init命令负责初始化项目骨架，也有gen命令负责在存量项目里按需生成模块代码。这两条路径互不干扰，共享同一套模板渲染内核。

1.3 工具选型的底层逻辑

在技术选型上，我没有犹豫就直接选了 Node.js。原因有三点：

第一，团队技术栈本身就是 TypeScript，CLI 工具用同一门语言，团队成员想扩展模板时零学习成本。

第二，Node.js 生态里现成的库非常全：commander处理命令行参数，ejs做模板渲染，chalk做带颜色的终端输出，prettier做生成后格式化，每一个都是久经考验的方案。

第三，跨平台。Windows、macOS、Linux 都可以直接跑，不需要额外装 Python 或 Go 工具链，这对团队推广很重要。

2. t3code 的分层架构与核心实现原理

2.1 三个核心模块的分工

t3code的内部结构并不复杂，我把它拆成了三层：命令解析层、模板渲染层、文件落盘与依赖安装层。每个模块的职责单一，方便后续单独替换。

命令解析层负责接住用户输入。比如你敲了t3code gen module user --crud，这一层会把gen和module解析出来，然后检查user这个模块名是否合法，以及当前目录下是否存在t3code.config.ts。这一步如果过不了，会直接给出友好报错，而不是让你等模板跑完才发现路径不对。

模板渲染层是整个工具的心脏。它要做的事情只有一件：把模板文件里的变量替换成真实值。但真正实现的时候比想象中要更讲究，因为模板不只是简单的字符串替换，还涉及循环、条件判断、嵌套路径。比如一个user模块要生成 controller、service、repository 三个文件，其中 service 里可能有分支逻辑：如果用户选了--auth，就要额外生成鉴权相关的代码块。这种动态逻辑靠ejs的<% if %>标签就能优雅处理。

文件落盘与依赖安装层负责最后一公里。渲染完成后，工具会在目标目录下创建对应的文件夹结构，把每个文件写入磁盘，然后根据配置决定是否自动安装依赖。这一步要处理的细节不少——目录存在时要不要覆盖？文件冲突时是提示还是跳过？Windows 路径下反斜杠和正斜杠混用怎么处理？这些都在后面踩坑部分细说。

2.2 配置驱动的设计

t3code的控制中心是一份t3code.config.ts文件，它类似于一份"项目蓝图"。

// t3code.config.ts import { defineConfig } from 't3code' export default defineConfig({ projectName: 'my-app', templateRoot: './templates', defaultPackageManager: 'npm', generatedDir: 'src/generated', variables: { author: 'Your Name', license: 'MIT', }, hooks: { afterGenerate: ['npm run lint:fix'], }, })

这份配置解决的关键问题是"约定优于配置"和"灵活可覆盖"之间的平衡。默认情况下，你什么都不写，t3code也有合理的默认值；但一旦项目有特殊要求，比如生成目录不想放在src/generated，或者生成后需要自动跑一下 lint 修复，都可以通过这份配置改掉。

我强烈建议你把这文件提交到 Git 仓库里，这样整个团队的生成规则就是受控的、可追溯的。谁改了配置，代码评审时能看到，而不是各自本地留着不同版本的脚本。

2.3 模板渲染的执行流程拆解

一次完整的t3code gen执行流程，按顺序是：

1. 读取t3code.config.ts，合并 CLI 传入的参数。
2. 定位模板根目录，扫描所有.ejs文件和非模板文件。
3. 构建模板变量上下文，比如{ moduleName: 'user', className: 'User', crud: true }。
4. 遍历模板文件，对每个.ejs文件执行渲染，将其余文件原样复制。
5. 计算每个文件的最终输出路径，处理路径模板变量。
6. 检查目标目录冲突，按策略覆盖或跳过。
7. 批量写文件，必要时调用prettier对生成的代码做格式化。
8. 若配置了 hooks，执行生成后的命令。

这个流程没有一步是高深的算法，但每一步的细节都决定工具好不好用。比如第 6 步，如果目标已存在同名文件，我会默认跳过而不是直接覆盖——因为你可能手改过生成物，自动覆盖会丢掉改动。最后再提示一句"以下文件已存在，未做修改"，让用户自己决定。

3. 从安装到跑通第一个模块：t3code 实操全流程

3.1 安装与初始化配置

安装非常简单，全局安装还是项目内安装，取决于你的使用习惯。我建议在项目级安装，这样不同项目可以锁不同版本的t3code。

npm install -D t3code

然后在项目根目录执行初始化：

npx t3code init

这条命令会做三件事：生成一份基础的t3code.config.ts，创建templates模板目录和generated输出目录，同时在工作目录里写入一份.gitignore示例。全部完成后终端会打印出下一步的提示，告诉你可以用t3code gen --help查看所有子命令。

3.2 常用命令一览

t3code的命令不多，但每个命令都对应一个高频场景。我把最常用的整理成了表格：

gen命令最常见的用法是t3code gen module user --crud，前面的module表示生成模块类型，user是模块名，--crud是参数，表示要生成完整的增删改查代码。这个设计使得工具不只是生成一个空文件，而是可以按需组合出不同复杂度的骨架。

3.3 实例：从一个空目录到一个可启动的 user 接口

下面我用一个完整场景演示。假设有一个空的 TypeScript 项目，只有最基础的package.json和tsconfig.json，现在要用t3code生成一个 user 模块。

第一步，初始化：

npx t3code init

第二步，生成模块：

npx t3code gen module user --crud

这会在src/generated/user目录下生成结构如下的文件：

src/generated/user/ ├── user.controller.ts ├── user.service.ts ├── user.repository.ts ├── user.routes.ts └── user.types.ts

user.controller.ts里已经写好了符合 RESTful 风格的路由函数——GET /user、GET /user/:id、POST /user、PUT /user/:id、DELETE /user/:id都预置了，返回结构按照项目配置里的统一格式来。user.service.ts有基础错误处理，user.repository.ts有数据库操作的占位实现，user.types.ts则根据模块名自动导出了User类型和CreateUserInput、UpdateUserInput等接口。

因为是--crud模式，工具还会自动在这些文件之间建立 import 关系，你不需要自己手动关联。所以生成完毕之后，只要把user.routes.ts挂载到应用入口，再补上数据库表结构，一个基础的用户接口就跑起来了。

3.4 参数组合与生成结果的关系

--crud只是其中一个选项。如果你只想要一个纯净的数据模型，可以执行t3code gen model user，它只生成类型定义和仓库层代码。想要带鉴权的版本，可以执行t3code gen module user --auth，会额外生成一个user.middleware.ts，里面预置了 Token 解析逻辑。

这些参数本质上就是模板变量。执行t3code gen module user --auth时，渲染上下文里会多一个auth: true的布尔值，模板里对应位置就会产出不同的代码分支。所以你完全不需要为每一种排列组合单独写一套模板，一份模板配合变量分支就够了。

4. 把团队规范沉淀到模板里：自定义扩展的完整方法

4.1 模板目录结构的设计

如果说命令和参数是t3code的骨架，那么模板目录就是它的血肉。默认模板目录结构是分层的：

templates/ ├── module/ │ ├── __name__.controller.ts.ejs │ ├── __name__.service.ts.ejs │ ├── __name__.repository.ts.ejs │ ├── __name__.routes.ts.ejs │ └── __name__.types.ts.ejs ├── model/ │ ├── __name__.model.ts.ejs │ └── __name__.repository.ts.ejs └── page/ ├── __name__.page.tsx.ejs └── __name__.styles.ts.ejs

顶层目录名对应gen命令的第一个参数（module、model、page），文件名里的__name__是命名单词，真实生成时会自动替换为user这种实际模块名。这个命名方式最初是参考 Ruby on Rails 的脚手架，因为__name__这种写法在任何操作系统上都是合法的文件名字符，不会因为斜杠或星号出问题。

.ejs后缀表示这是一个需要渲染的模板文件。不带这个后缀的文件会被原样复制——比如静态资源、配置文件模板、.gitkeep占位文件，都是直接复制的场景。

4.2 模板里能拿到哪些变量

搞懂t3code的模板变量系统，你才算真正掌握扩展能力。我设计了一个标准的上下文对象，每次渲染前都会自动构建：

• name：模块名，完全按照命令行输入的小写，比如user。
• className：转换为 PascalCase，比如User。
• fileName：转换为 kebab-case，比如user-profile。
• vars：来自配置文件的variables字段，可以塞任何团队共用信息，比如apiPrefix。
• flags：命令行里的布尔参数，比如--crud对应的crud字段就是true。
• timestamp：生成的时间戳，可以写进文件头。

举一个模板的实际例子。user.controller.ts.ejs里有这么一段：

import { Request, Response } from 'express'; import { <%= className %>Service } from './<%= name %>.service'; export class <%= className %>Controller { private service = new <%= className %>Service(); <% if (flags.crud) { %> async list(req: Request, res: Response) { const items = await this.service.findAll(); res.json({ code: 0, data: items }); } <% } %> }

name变量决定了 import 路径，className变量决定了类名，flags.crud控制是否生成 CRUD 方法。通过这种组合，同一套模板可以承担十几种不同形态的生成结果。

4.3 实操：自定义一个日志中间件模板

理解上面这套机制后，新增模板是水到渠成的事。我以自己的一个日志中间件为例。

在templates下新建middleware目录，创建文件__name__.middleware.ts.ejs：

import { Request, Response, NextFunction } from 'express'; import { logger } from '../core/logger'; export function <%= name %>Middleware(req: Request, res: Response, next: NextFunction) { const start = Date.now(); res.on('finish', () => { logger.info(`[<%= name %>] ${req.method} ${req.originalUrl} ${res.statusCode} - ${Date.now() - start}ms`); }); next(); }

然后执行t3code gen middleware request-logger，工具就会产出request-logger.middleware.ts，并自动把函数名替换成requestLoggerMiddleware。这个过程中你不需要动任何源码，只需要按模板约定放文件，t3code会把你所有.ejs文件当作待渲染模板，把其他文件原样复制。

4.4 团队模板的版本管理与协作建议

模板一旦多了，最大的风险不是写不出来，而是团队里各写各的，最后模板库变成一锅粥。

我在实际项目中总结了三条规矩：

第一，模板必须和业务代码一样做代码评审，不允许个人默默往主分支里塞模板。

第二，模板的变更要和生成物升级配套。修改模板后，需要在说明里写明"如何迁移已有的生成代码"，避免老代码和新模板产生割裂。

第三，定期做模板体检。用t3code doctor检查一遍所有模板是否存在坏引用、是否有文件残留、变量名是否拼写错误。这个命令就是为此设计的，每次升级后跑一遍能省很多事。

5. 实测中遇到的五个意外与我的处理方式

工具做出来只是第一步，真正让它变得可靠，靠的是在实际使用中暴露出的问题。下面这几个坑都是我在真实项目里踩过的，按照排查链路写出来，方便你遇到同类问题时参考。

5.1 Windows 路径分隔符引发的"文件找不到"

第一次在 Windows 上跑t3code，生成过程没有任何报错，但生成出来的代码在 import 路径里出现了user.controller.ts这种没问题，而某些深度嵌套的路径却用了反斜杠拼接，导致 Node 的模块解析直接失败。

根因是模板里用了 Node 的path.join()来拼接输出目录，这个函数在 Windows 上返回的是反斜杠，但业务代码里的 import 路径在 Webpack/Vite 之外的传统 Node 环境下，用反斜杠容易出问题。

解决方式有两个层次：首先，把模板中所有路径变量统一改成前端风格的正斜杠拼接，避免直接用path.join()的结果；其次，在文件落盘层加一个pathGuard函数，在写盘之前把所有路径标准化为平台兼容格式，同时把写入内容里的 import 路径二次校正。这里分享一个关键经验：生成工具的路径处理必须分成"写盘路径"和"代码内路径"两套逻辑来对待，前者交给操作系统的路径规则，后者坚持使用正斜杠。

5.2 EJS 模板转义冲突

第二个坑很隐蔽。有一个模板文件里需要生成 SWR 的缓存代码，里面有<%=开头的写法。结果渲染阶段直接崩溃，因为 EJS 把<%=识别成了自己的表达式标签。

排查时我先单独渲染了这个模板，反复确认没有一个变量被错误替换后，才意识到问题是字面上的 EJS 标签冲突。解决方案是给模板文件加了一个raw标记——你可以在模板目录中创建文件src/raw.txt（或者在特定的.ejs文件头部写<%# raw %>），让该文件跳过 EJS 渲染流程直接复制。

这个坑提醒我：不是所有带<%>的文件都适合用 EJS 渲染。尤其当你生成的代码是另一种模板语言时，必须为它准备逃生通道。

5.3 自动安装依赖时的"假成功"

我在配置里加了一个功能：如果模板里引入了新的 npm 包，生成后自动执行npm install。这个功能看着贴心，但实际运行时出现过很尴尬的情况——依赖装到一半网络抖动，npm install非零退出，但 CLI 没检测到，直接提示"生成完成"。

后来我加了一个步骤：执行完安装命令后，主动读一遍package.json，比对模板里声明的依赖版本，不匹配就报警告。这个校验不需要很严格，只需确认关键依赖存在即可，能避免大量"跑起来才发现少了包"的返工。这个思路引申出的经验是：生成器里所有"副作用操作"（安装、格式化、调试）都必须有事后校验，不能只关心命令是否执行，还关心执行结果是否真正生效。

5.4 生成文件后 Prettier 格式化失效

为了让生成出来的代码风格统一，我最早计划直接在写盘后调用prettier.format()。但测试时发现，部分生成文件在格式化后出现了引号、分号大换血，diff 一大堆，代码评审时很难看出来真正改动。

排查后发现不是 Prettier 的问题，而是.prettierrc只有在项目根目录存在时才会被加载，而生成的代码位于子目录中，某些情况下 Prettier 会向上查找配置但找不到，于是用了默认风格。

修复很简单：在调用prettier.format()时显式指定配置源，或者让t3code doctor检查项目中是否存在.prettierrc，如果缺失就提示用户。这个小修让生成代码第一次就和项目风格完全对齐。

5.5 并发生成同一模块时的文件冲突

很少人会一开始就想到并发问题，但团队里多人同时执行t3code gen module user时，确实出现过互相覆盖的现象。不同的人基于同一个模块名生成不同的自定义内容，最后一个写入者会覆盖前一个。

我的处理方式是引入文件锁：在输出目录写一个.t3code.lock文件，生成前检查该文件是否存在，存在则等待或取消；生成结束后再删除锁文件。如果遇上共享目录里多个实例并发，这种锁机制能保证生成操作是串行安全的。

6. 生成工具不是银弹：t3code 的边界与我的反思

6.1 哪些代码适合生成，哪些不适合

用了一段时间后，我慢慢摸清了t3code这类工具的适用范围。适合生成的是结构高度相似、逻辑相对机械、不随业务剧烈变化的代码，比如 CRUD 接口、数据模型定义、基础中间件、路由注册。这些代码最大的特点是"样式比逻辑更重要"，它们不会成为项目的核心竞争力。

不适合生成的是核心业务逻辑、复杂算法、强领域模型。你可能能生成一个看起来很完整的订单模块骨架，但订单状态机的流转、折扣计算规则、与支付网关的异常对账，这些细节高度依赖业务上下文，模板无法替你决策。如果硬要生成，只会得到一堆需要大改的残次品，改起来比直接从零写还要累。

6.2 模板膨胀是最大的长期风险

t3code的模板库最初只有 3 个模板，半年后膨胀到了 40 多个。模板膨胀带来的问题很现实：模板越多，维护成本越高，一旦底层依赖升级（比如从 Express 换到 Fastify），你就要挨个检查模板是否还能正确生成。

我的对策是定期合并相似模板。比如userAuthMiddleware、adminAuthMiddleware、apiKeyMiddleware本质都是"鉴权中间件"，最终合并成一个auth.middleware.ts.ejs，通过变量authType区分三种模式。模板数量砍掉了三分之一，维护负担也随之下降。任何工具做大了都会面对熵增，关键是定期做减法。

6.3 从生成代码到生成架构，还需要补一课

回看整个项目，我认为t3code目前最需要补的不是更多的命令，而是一种"架构感知"能力。现在的生成器只管产出独立文件，但真正优秀的代码生成应该理解模块之间的关系——生成 user 模块时，能否自动在路由注册表里加一行？生成 page 时，能否自动在菜单配置里注册入口？这些功能表面上只是"多写一行"，但实现起来需要把"项目结构"也纳入模板变量的范围，可以看作是t3code未来的演进方向。

6.4 给想把同类工具引入团队的几点现实建议

如果你也准备做类似的代码生成工具，我的建议是低起点开始。别一上来就规划庞大的模板库，先挑三条最重复、最让人烦躁的生成路径做通，拿给同事试用，根据真实反馈迭代。工具只有被人天天用，才会越改越好使。另一个建议是做好文档。t3code的每个模板都要求带一段"使用说明"，放在模板文件头部注释里，这样后来的人看到模板就能知道它生成什么、需要什么参数、产出物怎么接入，而不是靠一对一地口口相传。

最后补一句彩蛋： 我自己最常用到的一个小技巧，是在模板头部生成一段 `@generated` 注释——标明该文件由 `t3code` 生成、生成时间和所用模板版本。以后排查问题的时候，看到这个标记就知道这类代码不应该手改，要改就去改模板，再从源头重新生成。这个习惯对我的项目帮助特别大，推荐你也养成。