t3code 是我最近在维护的一个小工具，说起来很简单——一个跑在终端里的代码工具箱，专门处理三件事：代码片段查找、项目模板初始化、常用命令快捷方式管理。你如果和我一样，每天要在多个项目之间切换，新建工程时反复复制粘贴那套“基础设施”文件，又或者电脑里存了几百条代码片段却从来找不到想要的那条，那 t3code 就是冲着你去的。
开发这个工具的起因特别朴素。上个季度我连续开了四个新项目，每次都在重复同样的事情：mkdir 建目录、copy 配置文件、改 package name、粘贴 ESLint 规则。关键那个 ESLint 配置我还经常贴错版本。加上团队内部沉淀了不少代码规范片段，散落在 Wiki、聊天群和每个人的本地笔记里，每次用都要翻半天。我在想，能不能用一个命令把这一整套流程收敛掉，于是 t3code 就长成了现在这个样子。
t3code 这个名字没什么高深的含义：t 代表 Terminal，3 指它最核心的三块能力——snippet（代码片段）、template（项目模板）、alias（命令快捷方式），code 就是干活的本身。整个工具基于 Node.js 编写，没有图形界面，所有配置都是纯文本文件。对开发者而言，这反而是一个优势：配置可以放进 Git 仓库管理，换机器一条命令恢复，这比任何云同步方案都省心。
1. t3code 是什么：终端里的代码速建工具箱
1.1 为什么是终端：一个实用主义的选择
很多人问我，这年头做个工具为什么不带个 Web 界面或者做成 VS Code 插件？我一开始确实犹豫过，甚至写过一版带着简单 Web 面板的原型。后来发现，对于“取代码片段”和“建项目骨架”这种高频小操作，打开浏览器或者切换 IDE 窗口本身就是一种打断。终端的好处是：你本来就已经在里面了，输入一行命令，按下回车，完事。
还有一个更重要的理由——可脚本化。GUI 工具里的按钮很难被另一个程序调用，但终端工具可以。我可以在 CI 脚本里直接跑t3code template use生成项目骨架，可以在编辑器里绑定快捷键调出片段，甚至可以用 shell 的管道把 t3code 的输出交给其他命令二次处理。这些场景里，纯 CLI 是唯一靠谱的形态。
另外，终端的交互方式天然适合这类工具的操作频率。t3code 的所有交互都设计成“一次回答、直接出结果”：要么在命令里把参数写全，要么进入一个极简的问答流程，最多回答三个问题就完成操作。不会像某些脚手架那样连环提问二十个问题，答到后面已经忘了前面选了什么。
1.2 三段式架构：snippet、template、alias 的关系
t3code 把开发者日常重复劳动抽象成三个层级，这也是“3”字的来源。
第一层是 snippet，小零件的仓库。一段 React 函数组件怎么写、一个 Dockerfile 的基础模板长什么样、一条 grep 复杂日志的正则表达式是什么——这些粒度很小但高频使用的代码片段，统一存成带标签和变量的文件，用的时候模糊搜索匹配，回车即复制。
第二层是 template，整个项目的样板间。一个 Vue 3 + TypeScript 项目、一个 Node.js 服务端脚手架，这类包含几十个文件、还有相互依赖关系的项目骨架，靠单个片段是拼不出来的。template 模块把整个目录结构管起来，支持变量替换和文件重命名，一条命令就把完整的骨架铺到当前目录。
第三层是 alias，命令的快捷方式集合。我经常要跑一些固定组合的命令，比如“构建并部署到测试机”“打包后上传到内部源”。这种命令记不住、手敲容易错，alias 模块就是给它们加上一层可搜索的记忆。
三者的关系就像修房子：snippet 是五金件和螺丝，template 是整套施工图纸加建材包，alias 是你常用的那套电动工具和固定流程。工具最终要解决的，都是“别让我老干重复活”的问题。
1.3 本地优先：配置即代码
t3code 的所有数据都存放在用户目录下的~/.t3code/文件夹里，包括配置文件、代码片段、模板目录和日志。没有数据库，没有远程服务，没有隐性的网络请求。这一点是我刻意坚持的。
好处很明显。第一，所有内容都能被 Git 管理，我直接把~/.t3code放进了自己的 dotfiles 仓库，换电脑时git clone再加上t3code doctor一条命令就能完整恢复。第二，用户可以完全脱离我定义的存储结构，自己写脚本批量导入导出片段，甚至写个小程序生成模板。第三，不用担心数据泄露问题——代码片段很多时候涉及公司内部规范，存本地最安心。
本地优先的代价是少了“云端同步”的便利，但这个可以用 Git 仓库补位。我在后面“同步方案”一节里会具体讲怎么搭一套不依赖第三方云服务的同步机制。
2. 核心模块拆解：从设计思路到关键实现
2.1 snippet：让代码片段长上索引
代码片段的存储格式我调整过好几轮，最后定下来的方案是每个片段一个 JSON 对象，按语言或领域分文件存放。比如~/.t3code/snippets/javascript.json存 JS/TS 相关，~/.t3code/snippets/devops.json存 Docker、CI、Shell 相关。每个片段长这样：
{ "react-component": { "title": "React 函数组件（含 Props）", "tags": ["react", "component", "typescript"], "language": "typescript", "content": "import React from 'react';\n\ntype Props = {\n {{propName}}: {{propType}};\n};\n\nexport function {{componentName}}({ {{propName}} }: Props) {\n return <div>{{componentName}}</div>;\n}\n", "variables": { "componentName": { "default": "MyComponent" }, "propName": { "default": "data" }, "propType": { "default": "string" } } } }设计上我做了一个关键决定：不用代码模板引擎，只用最朴素的{{变量名}}占位符，替换逻辑自己写。原因是团队里有人会写 Python、Go、Rust，引入 Handlebars 或 EJS 意味着大家要学一套新的模板语法，学习成本不划算。而{{xxx}}这种格式，五分钟就能讲清楚，就算写错，替换失败也不会报出一堆难懂的模板引擎错误。
2.2 snippet 的变量替换逻辑
替换逻辑的核心其实就是一行正则：/\{\{\s*(\w+)\s*\}\}/g。系统先解析 content 里出现的所有变量名，再和 variables 字段里配置的默认值合并。用户执行t3code snippet get react-component时，如果某个变量没有默认值，会进入交互式问答；有默认值就直接回车跳过。
这个交互流程我想了挺久，最后定了一个原则：有默认值的变量绝不强制用户输入。默认值的存在就是为了让用户安静地接受它，而不是每次弹出问题打断心流。
实际使用中，有的变量名会出现在多个位置，比如{{componentName}}在函数名、组件标签里都出现。替换时机要统一——所有变量先收集、再一次性替换，避免前面替换生成的新字符串又匹配到后面的变量名，造成二次替换的“套娃问题”。
2.3 template：项目脚手架的标准化
模板模块解决的是更复杂的问题。一个现代前端项目的骨架可能包含几十个文件，里面还有复杂的目录结构、相互引用的文件路径。我的做法是：模板是一个真实的目录，目录里放对应的文件，文件名统一加.tpl后缀，需要变量替换的地方用占位符。另外每个模板根目录放一个_t3code.json元信息文件。
以我常用的 React + TypeScript 模板为例，目录结构是这样的：
~/.t3code/templates/react-ts/ ├── _t3code.json ├── package.json.tpl ├── tsconfig.json.tpl ├── vite.config.ts.tpl ├── index.html.tpl ├── README.md.tpl ├── public/ │ ├── favicon.svg.tpl └── src/ ├── main.tsx.tpl ├── App.tsx.tpl ├── App.css.tpl └── components/ └── Button.tsx.tpl每次执行t3code template use react-ts --name my-app时，流程是这样的：
- 读取
_t3code.json，拿到元信息和需要询问的变量清单。 - 把整个模板目录递归复制到当前目录，复制过程中排除
_t3code.json，并自动去掉.tpl后缀。 - 扫描复制出来的所有文本文件，执行变量替换。
- 根据
_t3code.json里的rename规则，对特定文件做重命名。 - 最后输出一份“生成文件清单”和改动统计，让用户一眼看清发生了什么。
2.4 变量替换之外：文件生成时的“保存问题”
复制过程中有个常见但不仔细想就会漏的细节：不同文件的编码和换行符不一样。Windows 上拉取的仓库常混着 CRLF 换行，替换完的模板文件如果原样保留 Windows 换行，到了 Linux 容器里就会出现一堆^M符号，ESLint 检查也会蹦出警告。所以 t3code 在替换变量后做了一道“归一化换行”的处理：统一转成\n，除非用户在配置里显式声明需要 CRLF（这种情况极少）。
另外一个坑是编码。模板目录里如果包含中文注释，文件可能是 UTF-8、GBK 或 GB2312。t3code 的统一策略是：只处理 UTF-8 文件，遇到无法解析的编码格式就原样拷贝，并在日志里提示用户检查。这是为了避免把用户原本用 GBK 保存的第三方模板强行转成 UTF-8，反而导致内容乱码。安全第一，处理不了就不处理，比处理错了强。
2.5 alias：给常用命令加一层记忆层
alias 模块的实现是最简单的，但也最容易被忽略。核心就一条：建立“别名 → 命令字符串”的映射，执行时代入到sh -c里跑。
t3code alias add deploy-fe "npm run build && scp -r dist user@server:/var/www/html" t3code alias run deploy-fe为什么不用 shell 自带的alias？因为 shell alias 有几个痛点：一是只在当前终端会话里生效，换窗口就没了；二是没法跨 shell（bash、zsh、fish 的别名语法不一样）；三是没有搜索发现能力。t3code 把别名统一存到配置文件里，任何终端输入t3code alias run deploy-fe都能执行，还能通过t3code alias list看看到底配了哪些命令。
不过我诚实说一句：如果你只需要一两个短别名，shell 原生的 alias 更轻快。t3code alias 是给“别名超过二十个、散落在三五台机器上”的人准备的。它适合存那种“多步组合、参数固定、每周要跑好几次”的长命令。
3. 实操：从安装到跑通第一个完整模板
3.1 环境准备与安装
t3code 要求 Node.js 18 及以上版本。为什么是 18？因为这个版本开始，Node 原生支持fetch和一些现代字符串 API，工具自身依赖会少一些，安装体积小，也更容易维护。如果本地还没装 Node 或者版本偏旧，建议直接用 nvm 装一个 LTS 版本，日常开发也够用。
安装方式有两种。第一种是全局安装：
npm install -g t3code如果你拿到了源码仓库，第二种更适合实际开发调试：
git clone https://github.com/yourname/t3code.git cd t3code npm install npm linknpm link会把当前目录软链到全局 bin 目录里，之后你在任何终端都能直接运行t3code，而且改代码即时生效，不需要反复重新安装。装完之后验证一下：
t3code --version t3code doctordoctor命令会检查 Node 版本、配置目录是否存在、模板目录是否可用，并给出修复建议。第一次使用建议先跑一遍，能省掉后面排查环境问题的时间。
3.2 初始化配置目录
安装后第一步是执行t3code init，它会创建~/.t3code/目录骨架，生成默认配置文件：
~/.t3code/ ├── config.json ├── snippets/ │ ├── javascript.json │ ├── devops.json │ └── default.json ├── templates/ └── logs/config.json是这个工具的总开关，里面包含几个关键选项：
{ "editor": "code", "defaultSnippetFile": "javascript.json", "variablePattern": "{{var}}", "strictMode": false, "theme": "default" }editor字段决定当你执行t3code snippet edit时用哪个编辑器打开文件。strictMode控制变量替换的严格程度——开启后，如果某个变量在content里出现但配置里没有对应值，会直接报错中断；关闭则静默保留原样。我开始默认开启，后来发现团队里有人不写variables字段、只想存一段纯文本，就改成了默认关闭。这个经验其实是踩出来的：工具的默认行为应该最大化兼容使用者的“懒”，而不是强制所有人写完整配置。
3.3 添加代码片段并完成首次查找
添加片段有两条路。一条是手动编辑 JSON 文件，适合一次添加多条；另一条是通过交互命令逐条添加：
# 进入交互式添加流程 t3code snippet add # 指定语言文件，直接传入内容（适合简单片段） t3code snippet add --file javascript --key "useeffect-cleanup" --title "useEffect 清理函数" --content "useEffect(() => {\n return () => { /* cleanup */ };\n}, []);"我个人更推荐“脚本式添加” + “手动编辑 JSON”的组合：日常遇到高频好用的片段，立刻用一行命令存下来，不让灵感过夜；批量整理已有笔记时，直接打开 JSON 文件一次贴入十几个片段，效率更高。
查找片段用get子命令：
# 模糊搜索并复制 t3code snippet get "useEffect" # 指定语言和标签过滤 t3code snippet get --language typescript --tag react --copy # 只要内容不进入交互，直接输出到 stdout t3code snippet get react-component --no-interactive第一次用get的读者可能注意到，我在这里加了--no-interactive选项。这个设计是为了配合管道使用：t3code snippet get react-component --no-interactive | pbcopy可以一键把片段内容复制到剪贴板（macOS 的pbcopy），或者接重定向写入某个文件。交互模式只能给人用，输出模式留给脚本，这两者是必须分开的。
3.4 初始化一个 React 项目：完整流程演示
下面演示一下如何用自己的模板初始化一个项目。先准备一个最简单的模板目录（我这里只展示核心文件）：
{ "name": "react-ts", "description": "React + TypeScript 基础项目骨架", "variables": { "projectName": { "description": "项目名，会写入 package.json", "default": "my-app" }, "author": { "description": "作者", "default": "" } }, "rename": {} }模板文件package.json.tpl内容如下：
{ "name": "{{projectName}}", "version": "0.1.0", "private": true, "author": "{{author}}", "scripts": { "dev": "vite", "build": "tsc && vite build" }, "dependencies": { "react": "^18.2.0", "react-dom": "^18.2.0" }, "devDependencies": { "typescript": "^5.0.0", "vite": "^4.0.0" } }src/App.tsx.tpl内容如下：
import React from 'react'; export default function App() { return ( <div className="app"> <h1>Welcome to {{projectName}}</h1> </div> ); }执行初始化命令：
# 在想要生成项目的目录下执行 t3code template use react-ts --projectName "dashboard" --author "Zhang San"运行后 t3code 会在当前目录生成package.json、src/App.tsx等已替换好内容的文件。其中package.json里的name会自动变成dashboard，App.tsx里的标题也会变成Welcome to dashboard。
这里有个很关键的体验细节：模板变量在交互式问答中提问的顺序，严格遵循_t3code.json里variables字段的书写顺序。JSON 对象在 JavaScript 里天然保证插入顺序，因此你能控制哪个问题先问、哪个后问。一般原则是：和其他问题关联度高的变量放前面，纯展示性的（像作者名）放后面。这个细节不做，用户就会觉得“这个交互怎么乱糟糟的”。
3.5 模板的覆盖策略与安全机制
初始化模板最怕一个场景：当前目录已经有文件，然后被脚手架直接覆盖。我之前用过某些脚手架工具，手一滑把整个项目目录覆盖了，那种“五分钟前的版本还没提交”的感觉真的太痛了。
所以 t3code 的默认策略是：如果目标文件已存在，直接跳过并记录日志，绝不自动覆盖。只有你在执行时附加--force参数，它才会用新内容覆盖旧文件。即便如此，被覆盖的旧文件也会先自动备份一份放到目录下的.t3code_backup_${timestamp}/文件夹里。这个备份机制后来救过我一次：有一次我命令里变量名写错了，导致替换后文件内容乱掉，靠备份文件夹里的原始文件挽回了损失。
4. 踩坑实录：这些问题我都替你试过了
4.1 命令找不到：全局安装后的 PATH 问题
第一个坑发生在安装阶段。有同事反馈“明明全局安装成功了，但输入 t3code 还是 command not found”。查了一下，他的 npm 全局 bin 目录没有被系统 PATH 包含。这种情况在 macOS 和 Linux 上都可能出现，尤其是在使用 nvm、n、volta 等 Node 版本管理工具的环境中。
排查方法很直接。先找到 npm 的全局 bin 目录：
npm bin -g # 或者 npm prefix -g然后把输出的目录追加到 shell 的 PATH 里。以 zsh 为例：
# ~/.zshrc export PATH="$(npm prefix -g)/bin:$PATH"这里我想多说一句：不要为了修这个问题去动系统级的/etc/paths或/etc/profile。改用户级配置文件就够，而且可随 dotfiles 仓库跨机器同步。另外，用 nvm 的用户要注意，nvm 切换 Node 版本后，全局安装的包不会跟着切过去。如果你经常切换 Node 版本，建议为每个 LTS 版本都重装一次 t3code，或者干脆用npm link从源码目录链接过来。
4.2 变量替换失败：特殊字符与 Windows 换行符
变量替换失败是使用频率最高的求助问题。我梳理了一下，真正的原因通常是这几类。
第一类是 JSON 转义问题。想在片段里放一段包含双引号的代码，直接在 JSON 文件里写双引号会破坏 JSON 结构。这种需要写成\"。我自己刚开始管理片段时也经常忘加反斜杠，所以后来在t3code snippet add命令里加了自动转义：从命令行传入的 content 会先做一次 JSON 转义再写入文件，这个函数虽然不起眼，但真的减少了很多低级错误。
第二类是特殊字符的问题。content字段里如果出现{{、}}之外的模板语法（如 JS 的模板字符串${}），系统里对${}是安全的，不会做额外替换。但如果你在模板里写了 shell 风格的$var，并且这段文本在普通字符串sh -c执行时被解析，就可能会遇到变量被 shell 吃掉的问题。最终解决方式是：在t3code alias run时一律用数组形式传给 shell，而不是先拼接成完整字符串再执行。
第三类是 Windows 换行符问题，前面提过了。文件从 Windows 上编辑后，模板文件里的 CRLF 会被原样保留，替换时如果正则的.没加m标志，跨行匹配就会出问题。现在的处理是在读取模板文件时就统一转换为\n，写回时再根据平台默认值决定输出。
第四类是编码问题。模板或片段文件如果不是 UTF-8，比如是 GBK 编码的中文，轻则中文注释乱码，重则整个文件解析失败。关于这个，我没有做全自动修复，因为自动检测编码的准确性永远存在风险。稳妥的做法是在执行t3code doctor时检查出非 UTF-8 文件并明确列出路径，让用户自己决定转换方式。毕竟，开发者自己的代码文件应该由开发者自己拍板用什么编码，工具不该替人做这个决定。
4.3 配置同步时的冲突：团队协作与多机同步
我自己用 Git 管理~/.t3code目录，等于给工具做了一层天然的同步方案。但同步过程中遇到过一个很经典的问题：两台电脑的 snippets 文件各自改了，合并时出现冲突。Git 的冲突标记会让 JSON 文件变成非法 JSON，导致t3code直接拒绝启动。
后来我的解决方案很简单：采用“小步提交+快速合并”的思路。每台机器上，新增一个片段后立刻 push，避免积累大量未同步的改动。如果真出现了冲突，解决方式不是手工编辑冲突标记，而是先将两份文件导出后做一次 JSON 合并，再用jq这类工具把结果写回。为了简化这个过程，我在 t3code 里加了一个t3code snippets merge命令，底层就是读入两个 JSON 文件按 key 合并，并以key冲突时“保留后来修改的那个”为原则。如果你也打算把配置目录交给 Git 管理，记住一件事：不要把日志文件纳入版本管理，在.gitignore里忽略logs/即可，否则每次运行都会产生一堆无意义的 diff。
4.4 与编辑器的集成：把 t3code 融进日常操作
t3code 定位是终端工具，但我知道很多人的日常操作主要在编辑器里完成。以 VS Code 为例，把 t3code 集成进去不需要写插件，用 Tasks 功能就能把“插入片段”变成一次快捷键操作。
先在项目根目录的.vscode/tasks.json里配置一个任务：
{ "version": "2.0.0", "tasks": [ { "label": "t3code: 插入片段", "type": "shell", "command": "t3code snippet get --no-interactive | pbcopy", "problemMatcher": [] } ] }然后到keybindings.json里绑定快捷键：
{ "key": "cmd+shift+i", "command": "workbench.action.tasks.runTask", "args": "t3code: 插入片段" }这样在编辑器里按下快捷键，t3code 会在终端里弹出一个模糊搜索列表，选中后内容直接进入剪贴板，再在代码里Cmd+V粘贴。它是一个“两步推进”的流程，看起来没有一步插入那么快，但好处是完全不依赖编辑器的插件 API，任何支持自定义任务的编辑器都能用。
4.5 一个印象最深的线上事故：模板变量名冲突导致的连锁替换
最后分享一个我印象比较深的坑，算是变量替换的“高级翻车现场”。当时我给模板设计了一个变量叫{{name}}，同时在package.json.tpl里用它来做包名。问题来了：模板里还有一段"author": "{{name}}"——这里的name我本意是作者名字，但变量替换时系统只认同名配置，结果两个位置都被替换成了项目名。整个仓库的认领人全变错了。
这个事故让我养成了一个习惯：模板变量的命名必须带上下文前缀。比如projectName和authorName，而不是模糊的name。如果再严厉一点，可以给 t3code 加一个变量作用域校验：声明时必须指定scope: "file"或scope: "template"，前者只对单个文件生效，后者作用于整个模板。这个功能我已经写进 v2 的规划里了。如果你自己搭类似的骨架工具，在这一块一定要一开始就想清楚，不然后期排查的成本很高。
5. 把 t3code 融入你的工作流：扩展思路与个人体会
5.1 与 CI 联动：在流水线里快速生成项目骨架
t3code 不只能用在本地开发机。因为它是纯 CLI，完全可以进入 CI/CD 流水线。我在公司的自动化流程里加过一个步骤：当内部平台需要大量生成微服务项目骨架时，直接调用下面的命令：
t3code template use node-service \ --serviceName "user-service" \ --owner "platform-team" \ --outDir "./generated"这个场景下，--no-interactive是必须的，因为流水线里没人坐在终端前回答变量问题。所有参数必须在命令中给出。这里我建议模板作者在_t3code.json里给每个变量都提供一个合理的默认值，即使是项目名这种关键变量，也可以定一个“待修改”的占位符。这样 CI 里即使某次调用漏传了参数，流水线也不会因为等待输入而挂起一整天。
5.2 更进一步：用钩子机制扩展自动化
t3code 目前内部有一套简单的事件钩子，在template use执行前和执行后会触发外部命令。比如我可以在config.json里配置：
{ "hooks": { "postTemplateUse": [ "npm install", "git init && git add -A && git commit -m 'chore: scaffold via t3code'" ], "preTemplateUse": [ "mkdir -p ./backup" ] } }这个机制让 t3code 从“复制模板”变成了“复制 + 初始化依赖 + 创建仓库”的一站式入口。每次新建项目，我跑完t3code template use，就自动进入一个已经装好依赖、建好 Git 仓库、准备好了第一次提交的状态。省掉的时间看起来每次只有几分钟，但一周开三四个项目，累积下来的效果就非常明显了。
5.3 做这个工具最大的收获：工具得贴合自己的工作流
做 t3code 这个项目，我自己最大的体会是：工具的形态永远是由使用者的工作流决定的。最初我参考了很多成熟的脚手架工具，想做得“功能全、选项多、配置复杂”，但实际用下来发现，真正高频的核心功能永远是那三四个——存片段、取片段、套模板、跑固定命令。
把功能收敛后，日常维护反而轻松了：代码量小了、文档清晰了、新同事上手也快了。很多人以为写工具要一步到位，其实更像打磨一把刀，磨一磨、用一用，再磨一磨，最终它才会贴合你的手掌。
t3code 没有做成一个“大而全的平台”，它只是一个在每个早晨帮你少敲几行重复命令的小助手。如果你手里也有类似的重复工作，我认为最好的做法不是等着别人造一个完美工具，而是拿一个周末，把你最烦的那个步骤抽象成配置，然后交给终端去执行。工具再小，只要解决了你的真问题，它就有持续进化的意义。
