从一周之内来回切换十多个工具、把团队里各种零散脚本攒成一个大杂烩仓库到最后自己动手做了一个统一入口的 CLI 工具箱“CLI-Anything”这个项目就这么被逼出来了。它不是什么重框架也不依赖什么神秘技术核心思路就是在终端里搞定日常高频操作查天气、记待办、取剪贴板图片、生成二维码、批量重命名、快速打开项目目录……所有东西收敛成一个命令入口你在任何一台机器上装上它就能按同一套心智模型做事情。这篇文章就把整个项目的来龙去脉写透为什么要做它、技术栈怎么选、核心模块怎么落地、插件机制怎么设计、以及我在实际开发中踩过的坑和排查链路。不管你是想把零散脚本收拾利索的开发者还是想给自己团队搭一套内部效率工具的运维或技术负责人这篇都值得看完再动手。1. 从“工具碎片化”的崩溃现场到CLI-Anything的目标边界1.1 痛点复盘真正难受的不是“没有工具”而是“工具太多”这个项目的起点有点狼狈。当时我手头同时维护几个服务端项目和一个前端项目协作工具还不统一A 组习惯用 JiraB 组用飞书表格发版要看 GitLab 流水线线上日志在 Kibana 里查配置文件散落在三个仓库里每次排查问题都要开一堆标签页并在终端、浏览器、IDE 之间来回切换。更难受的是我自己那台开发机上积累了一堆“一次性脚本”curl某个接口拿状态码、grep一段时间内的日志、用 node 脚本把 CSV 转成 JSON、再写个 awk 统计某个字段。坦白讲这些脚本每一段都能用但彼此之间没有统一入口。今天要用的时候我可能得花好几分钟回忆“上次那个统计脚本放在哪个目录下了”。时间一长情绪成本比时间成本还高。这种碎片化其实是很典型的工程问题单个工具都有自己的场景但工具之间的切换和记忆成本已经超过了工具本身带来的效率。CLI 工具的天然优势就是“只留一个入口、一切皆命令”它能把我们反复做的高频动作固定成肌肉记忆。1.2 给“Anything”划边界不是什么都做而是高频、轻量、可脚本化CLI-Anything 这个名字听起来很狂好像什么都要管。但没有边界的功能集合大概率会做成又一个什么都做不好的半成品。我需要先确定它的能力边界和取舍原则。我给自己定的三条标准是这样的高频每天或每周至少会用到一次的操作才值得收进来一年用两次的靠后站。轻量数据交互尽量通过终端文本完成不要让用户在一个微型 GUI 里去点按钮。可脚本化操作的结果要能被复制、被管道处理、被其他脚本消费否则不如直接打开对应软件。举个例子“查看今天的天气”这种功能放进 CLI 里价值非常高因为它本来就是一条网络请求加 JSON 解析的事而打开天气 App 还要经过解锁屏幕、点图标、看广告。但“写文档”就不适合做成 CLI即使做成也只会是个劣质的 Markdown 编辑器。1.3 最小原型先跑通一个命令再谈模块化第一版原型其实弱得可怜只有一个cli-anything hello命令输出一句问候语加一个读取配置文件的演示。整个代码没有超过 40 行npm init -y npm install commander#!/usr/bin/env node const { program } require(commander); program .name(cli-anything) .description(一个基于 Node.js 的万能 CLI 工具箱) .version(0.1.0); program .command(hello) .description(输出欢迎信息) .action(() { console.log(hello from cli-anything); }); program.parse();当时我刻意没有急着写“看起来有用”的功能。先跑通命令注册、参数解析、帮助文档渲染这些 CLI 的地基后面加功能模块的时候就只需要关心模块本身的业务逻辑了。这也是我想提醒每一个想自己写 CLI 工具的人别一上来就堆功能先把命令框架和配置骨架搭干净后面每一个模块都会轻松很多。2. 技术选型与架构设计为什么是 Node.js以及命令注册机制怎么写2.1 选型对比Node.js、Python 和 Go我最终选了哪个CLI 工具箱的骨架技术栈其实就那几条路Node.js、Python、Go。这三类我都写过一点小工具所以这轮对比不是凭想象而是基于实际体感。维度Node.jsPythonGo依赖安装与分发npm 生态成熟npm link本地调试方便pip 环境容易乱打包成单文件需要 PyInstaller交叉编译单二进制非常好但编译期略长第三方 CLI 框架commander、yargs 都很成熟click、typer 体验不错cobra 是经典选择JSON / 配置处理原生 JSON 支持读写都是顺手的事需要 json 模块写起来稍微绕需要定义结构体严谨但偏重团队上手成本前端团队普遍熟悉几乎无学习成本后端和运维熟悉也可以编译语言门槛稍高生态里有没有现成的库图片处理、二维码生成、HTTP 请求等库都很齐全同样丰富相比前两者略少最终选 Node.js 的核心原因其实是“心智负担最小”配置就用 JSON脚本跑起来不用考虑 Python 的虚拟环境npx和npm link让本地安装调试非常顺滑而且我所在团队本身就是前端技术栈后续想让别人也贡献力量几乎不用额外培训。如果你的团队是运维偏多那 Python 版本会更顺如果你追求极致的单文件分发那 Go 肯定是最优解。没有绝对答案只有适合你的答案。2.2 项目目录结构让新增一个命令只需要改一个文件我见过很多 CLI 工具所有代码堆在一个index.js里跑起来没问题但维护两三个月之后改个参数都提心吊胆。CLI-Anything 从一开始就按“命令即模块”的方式组织cli-anything/ ├── bin/ │ └── index.js # 入口只负责注册命令和加载模块 ├── src/ │ ├── commands/ # 每一个子命令一个文件 │ │ ├── weather.js │ │ ├── todo.js │ │ ├── image.js │ │ └── qr.js │ ├── core/ │ │ ├── config.js # 配置读写与校验 │ │ └── registry.js # 命令注册中心 │ └── utils/ │ ├── http.js # 带超时和重试的请求封装 │ └── file.js # 原子写入、路径处理等 ├── plugins/ # 第三方扩展插件目录 ├── package.json └── README.md入口文件bin/index.js的逻辑非常直白扫描src/commands目录拿到每个命令文件的描述信息然后注册到 commander 里。我用了一个极简的registry.js来做这件事// src/core/registry.js const fs require(fs); const path require(path); function loadCommands() { const commandsDir path.join(__dirname, ../commands); const files fs.readdirSync(commandsDir).filter((f) f.endsWith(.js)); const commands {}; for (const file of files) { const name path.basename(file, .js); commands[name] require(path.join(commandsDir, file)); } return commands; } module.exports { loadCommands };然后入口文件里这样用// bin/index.js const { program } require(commander); const { loadCommands } require(../src/core/registry); const commands loadCommands(); for (const [name, cmd] of Object.entries(commands)) { const sub program.command(name); cmd.register(sub); } program.parse();每个命令模块只需要暴露一个有register方法的对象这样“新增一个命令”就简化为“在 commands 目录下新建一个文件实现 register 方法”。不需要改任何公共代码也不会因为某一个命令的报错影响其他命令的加载。2.3 配置系统设计默认值、用户配置和运行时参数三层叠加CLI 工具箱最容易忽视却最关键的部分就是配置系统。用户可能希望“天气命令默认查北京”又可能希望在运行时临时查上海还可能改过一个全局配置文件。这套逻辑用三层配置叠加来解决默认配置内置在代码里写清楚每个参数的兜底值。用户配置读取~/.cli-anything/config.json覆盖默认值。运行时参数通过--city shanghai传入优先级最高。我当时用了一个很简单的mergeConfig函数同时用 zod 做了参数校验。这里需要注意的是用户配置文件如果写错了不能直接让整个工具崩溃而是应该给出清晰的错误提示并回退到默认配置。CLI 工具的容错性直接影响用户对它的信任度。3. 核心功能模块的落地实现天气、待办、图片和二维码3.1 weather 模块网络请求加上兜底逻辑而不是只调一个 API天气模块是典型“看起来简单做起来要想清楚”的功能。最直接的实现就是调一个天气 API然后JSON.parse输出。但实际操作中你会遇到两个问题网络可能超时、输入的城市名可能不规范。所以我把这个模块拆成三层第一层输入规范化。用户可能输入beijing、北京、北京市甚至拼音。要做城市名映射避免每次遗忘全称。第二层请求封装。统一走自研的http.js设置超时、自动重试一次。第三层输出格式。终端输出要简洁还要支持--json参数输出原始 JSON方便其他脚本消费。// src/commands/weather.js const { httpGet } require(../utils/http); async function fetchWeather(city) { const url https://api.example.com/weather?city${encodeURIComponent(city)}; const data await httpGet(url, { timeout: 5000, retries: 1 }); return { city: data.city, temperature: data.temperature, condition: data.condition, }; } function register(program) { program .command(weather) .description(查询某个城市的当前天气) .option(-c, --city city, 城市名称如北京, 上海) .option(-j, --json, 输出原始 JSON) .action(async (opts) { try { const result await fetchWeather(opts.city); if (opts.json) { console.log(JSON.stringify(result)); } else { console.log(当前 ${result.city}${result.temperature}℃${result.condition}); } } catch (err) { console.error(查询天气失败${err.message}); process.exit(1); } }); } module.exports { register };这里有一个我后来觉得特别重要的细节公共 HTTP 工具里一定要区分“业务错误”和“网络错误”。天气 API 返回 404、500和网络超时是完全不同的问题。如果混在一起提示用户根本不知道该去查城市名还是查网络。我在http.js里将错误对象都挂上了type字段这样每个命令模块就能给出更精准的错误提示。3.2 todo 模块JSON 文件持久化以及“原子写入”的教训待办事项模块要解决的问题是我需要一个比手机备忘录更快、比记事本文件更结构化的记录方式。CLI-Anything 用本地 JSON 文件存储待办命令包括add、list、done、delete。持久化文件放在了用户主目录下const path require(path); const os require(os); const dataFile path.join(os.homedir(), .cli-anything, todos.json);所有操作都是先读文件、改内存里的数组、再写回文件。但这里有一个必须在生产级工具里处理的细节原子写入。如果程序执行到一半断电或被杀掉直接把 JSON 原文件写破那用户所有待办数据就全毁了。我采用的方案是先写临时文件写入成功后rename覆盖原文件。因为rename在同一文件系统内是原子操作不会出现半个文件的状态// src/utils/file.js const fs require(fs); const path require(path); function atomicWriteJson(filePath, data) { const tmp ${filePath}.${process.pid}.tmp; fs.writeFileSync(tmp, JSON.stringify(data, null, 2), utf-8); fs.renameSync(tmp, filePath); } module.exports { atomicWriteJson };有了这个函数todo 模块写文件只需要一行atomicWriteJson(dataFile, todos)。团队里后来有人接手这个项目提了一个 issue 说“为什么写个待办还要这么绕”我把这行 rename 的原因讲清楚之后他反而去给自己其他脚本补了同样逻辑。数据文件的安全从来不是等坏了再修的事。3.3 image 模块把剪贴板里的图片直接存成文件这个模块是我的高频需求工作中经常要截个图发给同事、贴进文档但在服务器环境或纯终端工作流里打开图片编辑器再保存就很痛苦。于是我想做一条命令cli-anything image save --name screenshot.png把当前系统剪贴板里的图片保存到指定路径。在 macOS 上可以用pngpaste这样的辅助工具跨平台一点的做法是用社区维护的 clipboard 解析库。核心逻辑不复杂读取系统剪贴板判断内容类型是否为图片。如果第一步拿到的数据是 Buffer直接写入目标路径。提供--clipboard参数保存成功之后自动把文件路径复制回剪贴板方便立刻粘贴给别人。这里踩过一个真实的坑某些 Linux 桌面环境下剪贴板图片数据不是一次就能读完整的需要循环读取多次并拼接。如果没做这一层“等待数据稳定”的处理经常拿到半张图。后来我在代码里加了一个小循环每 100 毫秒尝试读取一次最多重试 10 次只有连续两次内容相同时才认为数据稳定。这个方案很土但实测稳定可靠。3.4 qr 模块把终端信息变成手机能扫的二维码二维码模块的实用场景特别多把服务器地址传给手机、把 WiFi 配置分享给同事、把一个长 JSON 配置转到手机扫码读取。终端里生成二维码如果不想依赖 GUI 库最直接的办法是输出到终端字符画或者输出一个二维码图片文件。CLI-Anything 的实现是这样的const QRCode require(qrcode); function register(program) { program .command(qr) .description(生成二维码可选输出到终端或保存为图片) .argument(text, 编码的内容) .option(-o, --output file, 保存为图片文件) .action(async (text, opts) { if (opts.output) { await QRCode.toFile(opts.output, text); console.log(二维码已保存到 ${opts.output}); } else { const terminal await QRCode.toString(text, { type: terminal }); console.log(terminal); } }); } module.exports { register };这可能是整个项目里代码量最少、但用户反馈最好的模块之一。因为它的价值不在于技术复杂度而在于“把信息从电脑传递到手机”这个动作被压缩到了一行命令里。以前我要么装第三方传文件工具、要么开聊天软件传给自己现在只要复制文本然后跑一条命令手机扫码即可。4. 插件机制从固定命令集合进化成真正的“Anything”4.1 契约定得越薄越好每个插件就是一个可以注册命令的文件CLI 工具发展到一定阶段一定会有人问我可不可以自己扩展命令如果每一个自定义命令都要改主仓库然后重新发布那这个工具就失去了“Anything”的意义。所以我在设计插件机制时定了一个很薄的契约一个插件本质上就是一个遵守规则的 Node.js 模块它导出register(program)方法package.json 里写上cli-anything-plugin关键字。主程序在启动时扫描两类位置内置的src/commands目录。用户配置文件里指定的pluginsDir目录。扫描到之后通过require加载然后调用它的register方法。没有复杂的依赖注入、没有插件生命周期就这十几行代码。薄契约最大的好处是降低参与者门槛任何人都可以在半小时内写一个自己的插件。4.2 插件扫描与动态注册的实现细节扫描逻辑和内置命令的加载几乎一样唯一区别是路径不同。考虑到用户可能安装了大量插件我还会在加载时做一层“防崩溃隔离”用try...catch单独包裹每个插件的加载过程任何一个插件报错只在终端打一条警告并不影响主程序启动和其他插件运行。// src/core/plugin.js function loadPlugins(pluginsDir) { if (!fs.existsSync(pluginsDir)) return []; const results []; const files fs.readdirSync(pluginsDir).filter((f) f.endsWith(.js)); for (const file of files) { try { const plugin require(path.join(pluginsDir, file)); results.push(plugin); } catch (err) { console.warn(插件加载失败${file}原因${err.message}); } } return results; }这里我特意没有用动态import()或更复杂的模块联邦机制原因很简单对于个人和团队内部工具文件系统扫描加require已经足够可靠引入花哨的插件加载框架只会增加心智负担和故障面。4.3 被忽略的细节插件里的依赖版本冲突插件机制上线两周后我收到了一个很典型的报错某插件用了commander的最新版而我主程序用的是旧版Node.js 的模块解析机制导致插件拿到的是主程序的commander实例于是报了版本不匹配。这个问题排查了很久最后发现根因是我把commander同时放在了主程序的dependencies和插件自己的dependencies里。解决方案其实不复杂要么约定所有插件都使用主程序提供的program实例不要自己 import 新的commander要么在主程序里做一次版本对齐检查。我选了第一种并在插件文档里加了一条醒目的约定“你的插件只需要接收program参数不要自己引入命令行框架。”这个约定让插件 API 更稳定也避免了依赖冲突。5. 踩坑实录从执行权限到网络兜底完整排查链路分享5.1 在 Windows 上跑不起cli-anythingPowerShell 执行策略的锅我把项目丢到 GitHub 之后第一个外部的 issue 来自一个 Windows 用户在 PowerShell 里输入cli-anything提示“无法加载文件因为在此系统上禁止运行脚本”。这个问题的根因很清晰PowerShell 默认的执行策略是Restricted禁止运行任何.ps1脚本而 npm 全局安装的命令本质上是通过一个 shell 脚本桥接启动的。排查链路就是三步先用npm ls -g确认包确实装到了全局。直接执行node C:\AppData\Roaming\npm\node_modules\cli-anything\bin\index.js如果能跑说明代码没问题问题出在 shim 层。执行Get-ExecutionPolicy确认执行策略。最终解决方法是建议用户运行Set-ExecutionPolicy -Scope CurrentUser RemoteSigned并解释这条策略的含义只禁止未签名的远程脚本本地脚本不受影响。这是比较安全的放宽方式不建议直接改成Unrestricted。这个问题的处理方式后来直接写进了 README 的 FAQ因为这个情况实在太普遍了。5.2 天气模块的“超时”排查是网络还是 API 限制第一次集中使用天气模块的时候我连续几次遇到“查询失败”。第一反应以为是网络问题但同样的时间段内curl一样的 API 却可以正常返回。于是我把排查拆成了三层抓原始错误信息打印err.message发现是socket hang up。对比手动请求和 CLI 请求的差异包括请求头、代理设置、连接复用逻辑。查 API 服务商的文档发现是免费层限制了单个 IP 每分钟的请求次数我早上的循环测试触发了限频。这个问题最终是靠两层解决请求头里设置了一个自定义的User-Agent部分服务商对默认 UA 会做更严格的限频同时在代码里增加了遇到 429 状态码时的退避等待逻辑。核心教训是CLI 工具里调用第三方 API必须把“限频”当成一类常规错误来处理而不是笼统地报“网络错误”。后来我还给http.js加了一个全局的小型令牌桶对用户高频重复调用做前置拦截避免触发服务商限频。5.3 待办文件被写坏的半夜现场从半个 JSON 到原子写入有一次我在测试 todo 的删除功能连续快速跑了十几条命令突然发现todos.json里出现了一个只有半个对象的内容。当时我没有立刻怀疑程序逻辑而是先去看进程是不是有多个命令同时启动导致两个进程同时读写同一个文件排查后确认确实存在并发写入。原因是我用了Promise.all并行执行几个待办命令的测试脚本两个 Node 进程同时writeFileSync最后一个写的内容把前一个覆盖就算了问题是在极端情况下写文件中途进程切换文件被写成了半截状态。修复方案就是我在 3.2 节里提到的原子写入临时文件加 rename。但这里有一个容易被忽略的补充点临时文件的命名一定要唯一。我当时用的是todos.json.${process.pid}.tmp如果测试脚本在一个进程里同时发起多次写入单靠 pid 是不够的还得带上时间戳或自增序号。后来我把命名改成了${process.pid}-${Date.now()}.tmp问题才彻底消失。5.4 参数校验全靠手写不用 zod 做运行时校验CLI 工具的输入是用户直接敲的字符串所以参数校验很重要。一开始我在每个命令里手写 if/else后来发现代码重复率越来越高错误提示也不统一。改用 zod 之后每个命令的校验逻辑变成声明式const schema z.object({ city: z.string().min(1, 城市名不能为空), days: z.number().int().min(1).max(14), });这样有两个好处一是校验规则一目了然二是 zod 的错误信息天然带中文自定义提示用户能直接看懂。更重要的是zod 的错误对象是结构化的我可以在入口处统一捕获以统一的格式打印出来。不是每个参数场景都需要这么重的校验但对于需要收 user 输入的 CLI这一层投入绝对值得。6. 实测体验、优化调整与后续扩展方向6.1 连续使用 15 天的体感数据与反馈工具大概在用了两周之后我统计了一下命令行工具的使用情况每天平均触发 20 次左右其中待办命令占了大头天气和二维码次之。最意外的是image save的使用频率因为平时截图真的太频繁了。有几个细节让我意识到这个方向是对的我渐渐不再去翻旧脚本目录了因为 cli-anything 的list子命令能直接列出所有可用命令和帮助信息。同事开始来问“这个命令怎么装”而不是继续用自己零散的脚本。有几次在服务器终端环境里需要查资料、生成二维码一条命令解决免去了本地装一堆图形工具的麻烦。这些反馈说明CLI 工具的价值不取决于功能多不多而取决于它是不是能让人形成“肌肉记忆”。形成肌肉记忆的前提是入口统一、响应快、输出稳定。6.2 可以继续扩展的方向消息推送、模板生成、云剪切板CLI-Anything 的插件机制铺好之后我脑子里马上闪过几个可以后续做的方向。第一个是“消息推送”在长任务结束时通过 Server酱或企业微信机器人推一条通知到手机。很多 CI 流水线已经支持这种能力但个人命令行工具尤其是本地跑的脚本很少能顺手推消息。如果做进 cli-anything用户在脚本里可以一行命令完成通知不用再各自配置 webhook。第二个是“模板生成”团队新建项目时需要初始化目录结构、配置文件、README 框架。这些完全是模板渲染的事做成命令比手动创建文件高效得多。而且模板文件本身可以放进一个独立的仓库用插件机制加载团队内部维护起来非常灵活。第三个是“云剪切板”在电脑 A 上复制一条配置在电脑 B 上拉取。基于最简单的键值对存储接口就能实现CLI 命令可以做clip write key和clip read key两个子命令。这个功能对经常在几台机器之间切换的开发者来说比传文件工具更方便。6.3 给想动手做 CLI 工具的人几条实在的建议最后分享几条我在这个项目上沉淀下来的经验都是踩过坑之后才真正理解的东西先做单命令原型再做框架抽象。我在实际写第一个可用命令之前花了太多时间在目录结构上其实应该先用一个命令把整条链路跑通比如命令行解析到输出打印。帮助信息要写到“小白也能看懂”。别默认用户看过你的 README每个命令的--help输出应该自带示例这是降低使用门槛最便宜的方式。错误输出要走 stderr不要跟正常结果混在 stdout 里。否则别人用管道处理你的输出时会把错误信息当成有效数据。为每一个新命令预设--json输出开关。这是最简单的“可脚本化”设计成本几乎为零但能大大扩展工具的适用场景。发布前至少要在一台干净机器上走一遍安装和卸载流程。很多依赖问题只在全新环境下暴露只在自己的开发机上测是永远测不出来的。回过头来看CLI-Anything 最值钱的不是某一条命令的实现而是把“想用命令行做任何事”的冲动变成了一套有边界、能扩展、敢长期依赖的工具骨架。如果你也在被各种工具切来切去搞得不耐烦不妨从一条最简单的命令开始把它养成你自己的“Anything”。
CLI-Anything：用Node.js打造统一入口的命令行效率工具箱
从一周之内来回切换十多个工具、把团队里各种零散脚本攒成一个大杂烩仓库到最后自己动手做了一个统一入口的 CLI 工具箱“CLI-Anything”这个项目就这么被逼出来了。它不是什么重框架也不依赖什么神秘技术核心思路就是在终端里搞定日常高频操作查天气、记待办、取剪贴板图片、生成二维码、批量重命名、快速打开项目目录……所有东西收敛成一个命令入口你在任何一台机器上装上它就能按同一套心智模型做事情。这篇文章就把整个项目的来龙去脉写透为什么要做它、技术栈怎么选、核心模块怎么落地、插件机制怎么设计、以及我在实际开发中踩过的坑和排查链路。不管你是想把零散脚本收拾利索的开发者还是想给自己团队搭一套内部效率工具的运维或技术负责人这篇都值得看完再动手。1. 从“工具碎片化”的崩溃现场到CLI-Anything的目标边界1.1 痛点复盘真正难受的不是“没有工具”而是“工具太多”这个项目的起点有点狼狈。当时我手头同时维护几个服务端项目和一个前端项目协作工具还不统一A 组习惯用 JiraB 组用飞书表格发版要看 GitLab 流水线线上日志在 Kibana 里查配置文件散落在三个仓库里每次排查问题都要开一堆标签页并在终端、浏览器、IDE 之间来回切换。更难受的是我自己那台开发机上积累了一堆“一次性脚本”curl某个接口拿状态码、grep一段时间内的日志、用 node 脚本把 CSV 转成 JSON、再写个 awk 统计某个字段。坦白讲这些脚本每一段都能用但彼此之间没有统一入口。今天要用的时候我可能得花好几分钟回忆“上次那个统计脚本放在哪个目录下了”。时间一长情绪成本比时间成本还高。这种碎片化其实是很典型的工程问题单个工具都有自己的场景但工具之间的切换和记忆成本已经超过了工具本身带来的效率。CLI 工具的天然优势就是“只留一个入口、一切皆命令”它能把我们反复做的高频动作固定成肌肉记忆。1.2 给“Anything”划边界不是什么都做而是高频、轻量、可脚本化CLI-Anything 这个名字听起来很狂好像什么都要管。但没有边界的功能集合大概率会做成又一个什么都做不好的半成品。我需要先确定它的能力边界和取舍原则。我给自己定的三条标准是这样的高频每天或每周至少会用到一次的操作才值得收进来一年用两次的靠后站。轻量数据交互尽量通过终端文本完成不要让用户在一个微型 GUI 里去点按钮。可脚本化操作的结果要能被复制、被管道处理、被其他脚本消费否则不如直接打开对应软件。举个例子“查看今天的天气”这种功能放进 CLI 里价值非常高因为它本来就是一条网络请求加 JSON 解析的事而打开天气 App 还要经过解锁屏幕、点图标、看广告。但“写文档”就不适合做成 CLI即使做成也只会是个劣质的 Markdown 编辑器。1.3 最小原型先跑通一个命令再谈模块化第一版原型其实弱得可怜只有一个cli-anything hello命令输出一句问候语加一个读取配置文件的演示。整个代码没有超过 40 行npm init -y npm install commander#!/usr/bin/env node const { program } require(commander); program .name(cli-anything) .description(一个基于 Node.js 的万能 CLI 工具箱) .version(0.1.0); program .command(hello) .description(输出欢迎信息) .action(() { console.log(hello from cli-anything); }); program.parse();当时我刻意没有急着写“看起来有用”的功能。先跑通命令注册、参数解析、帮助文档渲染这些 CLI 的地基后面加功能模块的时候就只需要关心模块本身的业务逻辑了。这也是我想提醒每一个想自己写 CLI 工具的人别一上来就堆功能先把命令框架和配置骨架搭干净后面每一个模块都会轻松很多。2. 技术选型与架构设计为什么是 Node.js以及命令注册机制怎么写2.1 选型对比Node.js、Python 和 Go我最终选了哪个CLI 工具箱的骨架技术栈其实就那几条路Node.js、Python、Go。这三类我都写过一点小工具所以这轮对比不是凭想象而是基于实际体感。维度Node.jsPythonGo依赖安装与分发npm 生态成熟npm link本地调试方便pip 环境容易乱打包成单文件需要 PyInstaller交叉编译单二进制非常好但编译期略长第三方 CLI 框架commander、yargs 都很成熟click、typer 体验不错cobra 是经典选择JSON / 配置处理原生 JSON 支持读写都是顺手的事需要 json 模块写起来稍微绕需要定义结构体严谨但偏重团队上手成本前端团队普遍熟悉几乎无学习成本后端和运维熟悉也可以编译语言门槛稍高生态里有没有现成的库图片处理、二维码生成、HTTP 请求等库都很齐全同样丰富相比前两者略少最终选 Node.js 的核心原因其实是“心智负担最小”配置就用 JSON脚本跑起来不用考虑 Python 的虚拟环境npx和npm link让本地安装调试非常顺滑而且我所在团队本身就是前端技术栈后续想让别人也贡献力量几乎不用额外培训。如果你的团队是运维偏多那 Python 版本会更顺如果你追求极致的单文件分发那 Go 肯定是最优解。没有绝对答案只有适合你的答案。2.2 项目目录结构让新增一个命令只需要改一个文件我见过很多 CLI 工具所有代码堆在一个index.js里跑起来没问题但维护两三个月之后改个参数都提心吊胆。CLI-Anything 从一开始就按“命令即模块”的方式组织cli-anything/ ├── bin/ │ └── index.js # 入口只负责注册命令和加载模块 ├── src/ │ ├── commands/ # 每一个子命令一个文件 │ │ ├── weather.js │ │ ├── todo.js │ │ ├── image.js │ │ └── qr.js │ ├── core/ │ │ ├── config.js # 配置读写与校验 │ │ └── registry.js # 命令注册中心 │ └── utils/ │ ├── http.js # 带超时和重试的请求封装 │ └── file.js # 原子写入、路径处理等 ├── plugins/ # 第三方扩展插件目录 ├── package.json └── README.md入口文件bin/index.js的逻辑非常直白扫描src/commands目录拿到每个命令文件的描述信息然后注册到 commander 里。我用了一个极简的registry.js来做这件事// src/core/registry.js const fs require(fs); const path require(path); function loadCommands() { const commandsDir path.join(__dirname, ../commands); const files fs.readdirSync(commandsDir).filter((f) f.endsWith(.js)); const commands {}; for (const file of files) { const name path.basename(file, .js); commands[name] require(path.join(commandsDir, file)); } return commands; } module.exports { loadCommands };然后入口文件里这样用// bin/index.js const { program } require(commander); const { loadCommands } require(../src/core/registry); const commands loadCommands(); for (const [name, cmd] of Object.entries(commands)) { const sub program.command(name); cmd.register(sub); } program.parse();每个命令模块只需要暴露一个有register方法的对象这样“新增一个命令”就简化为“在 commands 目录下新建一个文件实现 register 方法”。不需要改任何公共代码也不会因为某一个命令的报错影响其他命令的加载。2.3 配置系统设计默认值、用户配置和运行时参数三层叠加CLI 工具箱最容易忽视却最关键的部分就是配置系统。用户可能希望“天气命令默认查北京”又可能希望在运行时临时查上海还可能改过一个全局配置文件。这套逻辑用三层配置叠加来解决默认配置内置在代码里写清楚每个参数的兜底值。用户配置读取~/.cli-anything/config.json覆盖默认值。运行时参数通过--city shanghai传入优先级最高。我当时用了一个很简单的mergeConfig函数同时用 zod 做了参数校验。这里需要注意的是用户配置文件如果写错了不能直接让整个工具崩溃而是应该给出清晰的错误提示并回退到默认配置。CLI 工具的容错性直接影响用户对它的信任度。3. 核心功能模块的落地实现天气、待办、图片和二维码3.1 weather 模块网络请求加上兜底逻辑而不是只调一个 API天气模块是典型“看起来简单做起来要想清楚”的功能。最直接的实现就是调一个天气 API然后JSON.parse输出。但实际操作中你会遇到两个问题网络可能超时、输入的城市名可能不规范。所以我把这个模块拆成三层第一层输入规范化。用户可能输入beijing、北京、北京市甚至拼音。要做城市名映射避免每次遗忘全称。第二层请求封装。统一走自研的http.js设置超时、自动重试一次。第三层输出格式。终端输出要简洁还要支持--json参数输出原始 JSON方便其他脚本消费。// src/commands/weather.js const { httpGet } require(../utils/http); async function fetchWeather(city) { const url https://api.example.com/weather?city${encodeURIComponent(city)}; const data await httpGet(url, { timeout: 5000, retries: 1 }); return { city: data.city, temperature: data.temperature, condition: data.condition, }; } function register(program) { program .command(weather) .description(查询某个城市的当前天气) .option(-c, --city city, 城市名称如北京, 上海) .option(-j, --json, 输出原始 JSON) .action(async (opts) { try { const result await fetchWeather(opts.city); if (opts.json) { console.log(JSON.stringify(result)); } else { console.log(当前 ${result.city}${result.temperature}℃${result.condition}); } } catch (err) { console.error(查询天气失败${err.message}); process.exit(1); } }); } module.exports { register };这里有一个我后来觉得特别重要的细节公共 HTTP 工具里一定要区分“业务错误”和“网络错误”。天气 API 返回 404、500和网络超时是完全不同的问题。如果混在一起提示用户根本不知道该去查城市名还是查网络。我在http.js里将错误对象都挂上了type字段这样每个命令模块就能给出更精准的错误提示。3.2 todo 模块JSON 文件持久化以及“原子写入”的教训待办事项模块要解决的问题是我需要一个比手机备忘录更快、比记事本文件更结构化的记录方式。CLI-Anything 用本地 JSON 文件存储待办命令包括add、list、done、delete。持久化文件放在了用户主目录下const path require(path); const os require(os); const dataFile path.join(os.homedir(), .cli-anything, todos.json);所有操作都是先读文件、改内存里的数组、再写回文件。但这里有一个必须在生产级工具里处理的细节原子写入。如果程序执行到一半断电或被杀掉直接把 JSON 原文件写破那用户所有待办数据就全毁了。我采用的方案是先写临时文件写入成功后rename覆盖原文件。因为rename在同一文件系统内是原子操作不会出现半个文件的状态// src/utils/file.js const fs require(fs); const path require(path); function atomicWriteJson(filePath, data) { const tmp ${filePath}.${process.pid}.tmp; fs.writeFileSync(tmp, JSON.stringify(data, null, 2), utf-8); fs.renameSync(tmp, filePath); } module.exports { atomicWriteJson };有了这个函数todo 模块写文件只需要一行atomicWriteJson(dataFile, todos)。团队里后来有人接手这个项目提了一个 issue 说“为什么写个待办还要这么绕”我把这行 rename 的原因讲清楚之后他反而去给自己其他脚本补了同样逻辑。数据文件的安全从来不是等坏了再修的事。3.3 image 模块把剪贴板里的图片直接存成文件这个模块是我的高频需求工作中经常要截个图发给同事、贴进文档但在服务器环境或纯终端工作流里打开图片编辑器再保存就很痛苦。于是我想做一条命令cli-anything image save --name screenshot.png把当前系统剪贴板里的图片保存到指定路径。在 macOS 上可以用pngpaste这样的辅助工具跨平台一点的做法是用社区维护的 clipboard 解析库。核心逻辑不复杂读取系统剪贴板判断内容类型是否为图片。如果第一步拿到的数据是 Buffer直接写入目标路径。提供--clipboard参数保存成功之后自动把文件路径复制回剪贴板方便立刻粘贴给别人。这里踩过一个真实的坑某些 Linux 桌面环境下剪贴板图片数据不是一次就能读完整的需要循环读取多次并拼接。如果没做这一层“等待数据稳定”的处理经常拿到半张图。后来我在代码里加了一个小循环每 100 毫秒尝试读取一次最多重试 10 次只有连续两次内容相同时才认为数据稳定。这个方案很土但实测稳定可靠。3.4 qr 模块把终端信息变成手机能扫的二维码二维码模块的实用场景特别多把服务器地址传给手机、把 WiFi 配置分享给同事、把一个长 JSON 配置转到手机扫码读取。终端里生成二维码如果不想依赖 GUI 库最直接的办法是输出到终端字符画或者输出一个二维码图片文件。CLI-Anything 的实现是这样的const QRCode require(qrcode); function register(program) { program .command(qr) .description(生成二维码可选输出到终端或保存为图片) .argument(text, 编码的内容) .option(-o, --output file, 保存为图片文件) .action(async (text, opts) { if (opts.output) { await QRCode.toFile(opts.output, text); console.log(二维码已保存到 ${opts.output}); } else { const terminal await QRCode.toString(text, { type: terminal }); console.log(terminal); } }); } module.exports { register };这可能是整个项目里代码量最少、但用户反馈最好的模块之一。因为它的价值不在于技术复杂度而在于“把信息从电脑传递到手机”这个动作被压缩到了一行命令里。以前我要么装第三方传文件工具、要么开聊天软件传给自己现在只要复制文本然后跑一条命令手机扫码即可。4. 插件机制从固定命令集合进化成真正的“Anything”4.1 契约定得越薄越好每个插件就是一个可以注册命令的文件CLI 工具发展到一定阶段一定会有人问我可不可以自己扩展命令如果每一个自定义命令都要改主仓库然后重新发布那这个工具就失去了“Anything”的意义。所以我在设计插件机制时定了一个很薄的契约一个插件本质上就是一个遵守规则的 Node.js 模块它导出register(program)方法package.json 里写上cli-anything-plugin关键字。主程序在启动时扫描两类位置内置的src/commands目录。用户配置文件里指定的pluginsDir目录。扫描到之后通过require加载然后调用它的register方法。没有复杂的依赖注入、没有插件生命周期就这十几行代码。薄契约最大的好处是降低参与者门槛任何人都可以在半小时内写一个自己的插件。4.2 插件扫描与动态注册的实现细节扫描逻辑和内置命令的加载几乎一样唯一区别是路径不同。考虑到用户可能安装了大量插件我还会在加载时做一层“防崩溃隔离”用try...catch单独包裹每个插件的加载过程任何一个插件报错只在终端打一条警告并不影响主程序启动和其他插件运行。// src/core/plugin.js function loadPlugins(pluginsDir) { if (!fs.existsSync(pluginsDir)) return []; const results []; const files fs.readdirSync(pluginsDir).filter((f) f.endsWith(.js)); for (const file of files) { try { const plugin require(path.join(pluginsDir, file)); results.push(plugin); } catch (err) { console.warn(插件加载失败${file}原因${err.message}); } } return results; }这里我特意没有用动态import()或更复杂的模块联邦机制原因很简单对于个人和团队内部工具文件系统扫描加require已经足够可靠引入花哨的插件加载框架只会增加心智负担和故障面。4.3 被忽略的细节插件里的依赖版本冲突插件机制上线两周后我收到了一个很典型的报错某插件用了commander的最新版而我主程序用的是旧版Node.js 的模块解析机制导致插件拿到的是主程序的commander实例于是报了版本不匹配。这个问题排查了很久最后发现根因是我把commander同时放在了主程序的dependencies和插件自己的dependencies里。解决方案其实不复杂要么约定所有插件都使用主程序提供的program实例不要自己 import 新的commander要么在主程序里做一次版本对齐检查。我选了第一种并在插件文档里加了一条醒目的约定“你的插件只需要接收program参数不要自己引入命令行框架。”这个约定让插件 API 更稳定也避免了依赖冲突。5. 踩坑实录从执行权限到网络兜底完整排查链路分享5.1 在 Windows 上跑不起cli-anythingPowerShell 执行策略的锅我把项目丢到 GitHub 之后第一个外部的 issue 来自一个 Windows 用户在 PowerShell 里输入cli-anything提示“无法加载文件因为在此系统上禁止运行脚本”。这个问题的根因很清晰PowerShell 默认的执行策略是Restricted禁止运行任何.ps1脚本而 npm 全局安装的命令本质上是通过一个 shell 脚本桥接启动的。排查链路就是三步先用npm ls -g确认包确实装到了全局。直接执行node C:\AppData\Roaming\npm\node_modules\cli-anything\bin\index.js如果能跑说明代码没问题问题出在 shim 层。执行Get-ExecutionPolicy确认执行策略。最终解决方法是建议用户运行Set-ExecutionPolicy -Scope CurrentUser RemoteSigned并解释这条策略的含义只禁止未签名的远程脚本本地脚本不受影响。这是比较安全的放宽方式不建议直接改成Unrestricted。这个问题的处理方式后来直接写进了 README 的 FAQ因为这个情况实在太普遍了。5.2 天气模块的“超时”排查是网络还是 API 限制第一次集中使用天气模块的时候我连续几次遇到“查询失败”。第一反应以为是网络问题但同样的时间段内curl一样的 API 却可以正常返回。于是我把排查拆成了三层抓原始错误信息打印err.message发现是socket hang up。对比手动请求和 CLI 请求的差异包括请求头、代理设置、连接复用逻辑。查 API 服务商的文档发现是免费层限制了单个 IP 每分钟的请求次数我早上的循环测试触发了限频。这个问题最终是靠两层解决请求头里设置了一个自定义的User-Agent部分服务商对默认 UA 会做更严格的限频同时在代码里增加了遇到 429 状态码时的退避等待逻辑。核心教训是CLI 工具里调用第三方 API必须把“限频”当成一类常规错误来处理而不是笼统地报“网络错误”。后来我还给http.js加了一个全局的小型令牌桶对用户高频重复调用做前置拦截避免触发服务商限频。5.3 待办文件被写坏的半夜现场从半个 JSON 到原子写入有一次我在测试 todo 的删除功能连续快速跑了十几条命令突然发现todos.json里出现了一个只有半个对象的内容。当时我没有立刻怀疑程序逻辑而是先去看进程是不是有多个命令同时启动导致两个进程同时读写同一个文件排查后确认确实存在并发写入。原因是我用了Promise.all并行执行几个待办命令的测试脚本两个 Node 进程同时writeFileSync最后一个写的内容把前一个覆盖就算了问题是在极端情况下写文件中途进程切换文件被写成了半截状态。修复方案就是我在 3.2 节里提到的原子写入临时文件加 rename。但这里有一个容易被忽略的补充点临时文件的命名一定要唯一。我当时用的是todos.json.${process.pid}.tmp如果测试脚本在一个进程里同时发起多次写入单靠 pid 是不够的还得带上时间戳或自增序号。后来我把命名改成了${process.pid}-${Date.now()}.tmp问题才彻底消失。5.4 参数校验全靠手写不用 zod 做运行时校验CLI 工具的输入是用户直接敲的字符串所以参数校验很重要。一开始我在每个命令里手写 if/else后来发现代码重复率越来越高错误提示也不统一。改用 zod 之后每个命令的校验逻辑变成声明式const schema z.object({ city: z.string().min(1, 城市名不能为空), days: z.number().int().min(1).max(14), });这样有两个好处一是校验规则一目了然二是 zod 的错误信息天然带中文自定义提示用户能直接看懂。更重要的是zod 的错误对象是结构化的我可以在入口处统一捕获以统一的格式打印出来。不是每个参数场景都需要这么重的校验但对于需要收 user 输入的 CLI这一层投入绝对值得。6. 实测体验、优化调整与后续扩展方向6.1 连续使用 15 天的体感数据与反馈工具大概在用了两周之后我统计了一下命令行工具的使用情况每天平均触发 20 次左右其中待办命令占了大头天气和二维码次之。最意外的是image save的使用频率因为平时截图真的太频繁了。有几个细节让我意识到这个方向是对的我渐渐不再去翻旧脚本目录了因为 cli-anything 的list子命令能直接列出所有可用命令和帮助信息。同事开始来问“这个命令怎么装”而不是继续用自己零散的脚本。有几次在服务器终端环境里需要查资料、生成二维码一条命令解决免去了本地装一堆图形工具的麻烦。这些反馈说明CLI 工具的价值不取决于功能多不多而取决于它是不是能让人形成“肌肉记忆”。形成肌肉记忆的前提是入口统一、响应快、输出稳定。6.2 可以继续扩展的方向消息推送、模板生成、云剪切板CLI-Anything 的插件机制铺好之后我脑子里马上闪过几个可以后续做的方向。第一个是“消息推送”在长任务结束时通过 Server酱或企业微信机器人推一条通知到手机。很多 CI 流水线已经支持这种能力但个人命令行工具尤其是本地跑的脚本很少能顺手推消息。如果做进 cli-anything用户在脚本里可以一行命令完成通知不用再各自配置 webhook。第二个是“模板生成”团队新建项目时需要初始化目录结构、配置文件、README 框架。这些完全是模板渲染的事做成命令比手动创建文件高效得多。而且模板文件本身可以放进一个独立的仓库用插件机制加载团队内部维护起来非常灵活。第三个是“云剪切板”在电脑 A 上复制一条配置在电脑 B 上拉取。基于最简单的键值对存储接口就能实现CLI 命令可以做clip write key和clip read key两个子命令。这个功能对经常在几台机器之间切换的开发者来说比传文件工具更方便。6.3 给想动手做 CLI 工具的人几条实在的建议最后分享几条我在这个项目上沉淀下来的经验都是踩过坑之后才真正理解的东西先做单命令原型再做框架抽象。我在实际写第一个可用命令之前花了太多时间在目录结构上其实应该先用一个命令把整条链路跑通比如命令行解析到输出打印。帮助信息要写到“小白也能看懂”。别默认用户看过你的 README每个命令的--help输出应该自带示例这是降低使用门槛最便宜的方式。错误输出要走 stderr不要跟正常结果混在 stdout 里。否则别人用管道处理你的输出时会把错误信息当成有效数据。为每一个新命令预设--json输出开关。这是最简单的“可脚本化”设计成本几乎为零但能大大扩展工具的适用场景。发布前至少要在一台干净机器上走一遍安装和卸载流程。很多依赖问题只在全新环境下暴露只在自己的开发机上测是永远测不出来的。回过头来看CLI-Anything 最值钱的不是某一条命令的实现而是把“想用命令行做任何事”的冲动变成了一套有边界、能扩展、敢长期依赖的工具骨架。如果你也在被各种工具切来切去搞得不耐烦不妨从一条最简单的命令开始把它养成你自己的“Anything”。
