做完一个叫 CLI-Anything 的小项目之后，我最大的感受是：命令行工具原来可以不用一个个硬编码，而是“描述出来”的。CLI-Anything 的定位一句话就能说清——你给它一份 JSON 或 YAML 描述文件，它就把里边的命令、参数、选项、执行逻辑全部变成一套可交互、带校验、有进度反馈的完整命令行工具。这个思路解决了我最头疼的问题：团队里散落十几个脚本，入口五花八门，参数全靠猜，新人来了完全不敢碰。如果你也经常在终端里跑重复工作流，或者维护着一堆零散脚本，这篇文章会讲清楚 CLI-Anything 的核心设计、手写实现思路，以及我在真实项目里踩过的坑，希望能让你少走一段弯路。
1. 项目定位：CLI-Anything 到底在解决什么问题
1.1 脚本泛滥与“CLI 三难”
我见过太多这样的项目：根目录下一堆build.sh、deploy.py、batch_process.js，每个人写的入口都不一样。有的脚本接受环境变量，有的靠修改文件头部常量，有的干脆就是“直接改最后三行”。你问这个脚本怎么用，写的人自己都要翻半天代码才能想起来参数是--input还是-i，输出写到哪儿去了。
这种混乱状态背后其实就三个问题，我叫它“CLI 三难”。第一是参数难传：脚本的参数校验完全随缘，传错了不会报错，只会产生一个稀里糊涂的结果。第二是帮助难查：没有--help，没有补全，使用者只能靠猜和翻源码。第三是行为难以组合：脚本之间不能通过管道传递结果，更没法在 CI 里稳定调用，因为退出码有时是 0，有时是 1，全看心情。
CLI-Anything 的出发点就是把这“三难”一次性解决。它的思路不是写一个新的命令行框架让你从头撸代码，而是把命令的定义和执行彻底分离——你用一份配置文件描述“这个命令叫什么、接收什么参数、执行哪段逻辑”，运行时负责解析、校验、调用和输出。这样一来，散落的脚本逻辑可以原封不动地变成一个个标准命令，但使用体验完全不同了。
1.2 为什么用描述文件驱动，而不是传统硬编码
有人可能会问，Node 生态有 commander、Python 有 click、Go 有 cobra，这些成熟框架不好吗？它们当然好，我自己也常用。但当你同时维护十几个脚本，且这些脚本的语言还不一样时，问题就变成了“每个脚本都要单独写一套 CLI 壳”。用 commander 写一个命令，至少得写program.command(...).option(...).action(...)这一套，代码量不大，但量变引起质变，而且每个脚本的写法还不统一。
CLI-Anything 选择“描述文件驱动”的核心原因是：配置是数据，而数据可以被多种工具消费。同一个cli-anything.json，既能生成命令行入口，又能被 CI 用来检查帮助文本，还能自动生成 README 的命令列表。这就把“写 CLI 壳”这件事从写代码降维成了写配置，任何会 JSON 语法的人都能维护。
当然这个取舍不是没有代价。描述驱动的表达能力有限，复杂交互逻辑还是得落到 handler 文件里写代码，所以 CLI-Anything 的设计哲学是“配置负责解析与路由，代码负责逻辑与渲染”。分清边界之后，灵活性和规范性都能保住。
1.3 感性认识：一个命令从“跑不通”到“跑得爽”
空讲概念不如直接看例子。这是一份最简单的配置文件：
{ "name": "demo", "commands": [ { "name": "hello", "description": "跟你打个招呼", "arguments": [ { "name": "name", "type": "string", "required": true } ], "handler": "commands/hello.js" } ] }配合一个不到五行的commands/hello.js：
module.exports = async function ({ values }) { console.log(`Hello, ${values.name}!`); };运行起来就是：
$ ca hello world Hello, world! $ ca hello 缺少参数 <name> 在终端里敲下命令的瞬间，参数校验、帮助提示、执行调用全都有了。这只是一个最小样例，但它已经把 CLI-Anything 最核心的体验传递出来了：描述命令，而不是编写命令。 ## 2. 核心机制：拆开 CLI-Anything 的四大骨架 ### 2.1 命令注册与路由：argv 如何变成指令 命令行的本质是接收一个字符串数组，也就是 `process.argv` 去掉前两项之后剩下的部分。CLI-Anything 要做的第一件事，就是把这个数组解析成“用户意图”。比如 `ca md2html ./docs --output ./site` 这个字符串，应该被拆成“命令名 md2html、位置参数 ./docs、选项 output ./site”。 注册阶段会把配置文件里的所有命令构建成一个路由表，常用 `Map` 结构，键是命令名，值是完整的命令定义。匹配时先找第一个不以 `-` 开头的 token，拿去查路由表，命中就继续解析剩余部分，没命中就输出“命令不存在”并返回退出码 2。这一步听起来简单，但实际项目里要注意子命令问题。如果你的命令是 `ca doc build` 这种两级结构，那么路由表就要设计成支持嵌套，而不是简单的一层 `Map`。我在 CLI-Anything 里用的办法是构建一颗命令树，每个节点都可以有自己的 subcommands，匹配时逐层下钻，直到叶子节点。 路由这层还要处理一个特殊情况：`--help`。用户敲 `ca build --help` 时，不应该再去做参数校验和 handler 调用，而是直接打印这个命令的完整说明。所以匹配到命令节点后，我会先检查剩余 token 里有没有 `-h` 或 `--help`，有的话就进入帮助输出流程，整个解析流程直接短路。 ### 2.2 参数解析与类型校验：CLI 的“地板”不能晃 参数解析是命令行工具最容易做烂的部分。用户在终端里输入的全是字符串，但你的业务逻辑可能需要 number、boolean、数组甚至枚举，这就需要一个从字符串到具体类型的转换层，同时还要处理缺参、多参、非法枚举值等情况。 CLI-Anything 的参数模型分成两类：位置参数 arguments 和选项 options。位置参数按顺序解析，定义时声明 required 来决定是否必须。选项则是 `--key value` 或 `--key=value` 形式，支持 boolean 开关和默认值。类型转换我实现了一个 `coerce` 函数：`Number(raw)` 给 number 类型，`raw === "true"` 给 boolean 类型，`String(raw).split(",")` 给 array 类型。逻辑不复杂，但错误处理必须给足信息。 校验的优先级也需要想清楚。我的顺序是：先解析位置参数，再解析选项，最后统一做默认值填充和枚举校验。之所以把默认值填充放在最后，是因为用户传了值和没传值应该走不同路径，不能一上来就填默认值然后把用户传的值覆盖掉。举个典型场景：某个选项同时声明了 `default: "normal"` 和 `enum: ["high", "normal", "low"]`，如果用户显式传了 `--priority high`，那默认值就不能再参与任何判断。 ### 2.3 执行引擎与插件体系：让命令“长”出来 CLI-Anything 的执行流程是一条清晰的责任链：加载器读取配置，注册器构建命令路由，解析器处理 argv，校验器检查参数，最后运行器加载 handler 文件并调用。每个环节各司其职，这样任何一个环节要做替换或扩展，都不会波及其他部分。 handler 是真正的业务逻辑所在，CLI-Anything 对它的接口约定很轻：导出一个异步函数，接收一个上下文对象 `{ values, cwd }`，`values` 是解析校验后的参数集合，`cwd` 是当前工作目录。为什么把上下文收敛成一个对象而不是散装传参？因为这样后续扩展时不需要改函数签名。比如以后我想在上下文里加一个 `logger` 对象，或者加一个 `getConfig()` 方法，所有现有 handler 都不用动，只是多了可用能力。 “插件”这个东西在描述驱动框架里其实有两层含义。一层是框架层面的插件：比如你想新增一种参数类型 `path`，可以扩展解析器的类型表。另一层是业务层面的扩展：一个命令执行前和执行后往往需要做统一处理，比如打日志、计时、上报埋点。CLI-Anything 在运行器里预留了 `beforeHandler` 和 `afterHandler` 两个钩子，配置好之后每次执行命令都会走一遍，这让很多横切逻辑不用到处复制粘贴。 ### 2.4 输出与交互约定：好 CLI 的一半是“体面” 工具好用不好用，一半取决于参数设计，另一半取决于输出设计。CLI-Anything 从一开始就约定了几件事。 stdout 只输出业务数据，stderr 只输出错误和日志。这个约定在终端直接看可能觉得无所谓，但一旦你写 `ca md2html ./docs | grep done`，stdout 里混进几行日志，管道解析就会崩。退出码同样重要：0 代表成功，1 代表参数或运行时错误，2 代表命令找不到。很多脚本不在乎退出码，结果 CI 跑挂了都不知道挂在哪一步。 交互体验上，进度反馈是用户感知最明显的部分。console.log 会带上换行，刷新进度条时会看到满屏滚动，正确的做法是用 `process.stdout.write("\r...")`，通过回车符让光标回到行首重新绘制。CLI-Anything 内置了一个简单的进度条渲染函数，后面实操部分我会给出核心代码。还有一个小细节：非交互环境下不要输出 ANSI 颜色和进度条，否则 CI 日志会变得很难看。判断方式很简单，`!process.stdout.isTTY` 时就把进度输出退化成普通日志。 ## 3. 实操：从零手写一个最小可用 CLI-Anything ### 3.1 目录设计与初始化 理论讲完，直接上手写一个能跑的最小实现。我会用 Node.js 的 CommonJS 模块，零第三方依赖，核心代码两百行左右。这样做的目的是让你看清每一行在干什么，不被依赖库的魔法掩盖。 项目结构这样安排： ```text cli-anything/ ├── package.json ├── bin/ │ └── cli.js ├── lib/ │ ├── loader.js │ ├── registry.js │ ├── parser.js │ └── runner.js └── commands/ └── md2html.jsbin目录放可执行入口，lib放框架核心，commands放具体的业务 handler。package.json 里声明bin字段，这样通过 npm link 就能在终端敲一个全局命令名。
初始化 package.json：
{ "name": "cli-anything", "version": "0.1.0", "bin": { "ca": "bin/cli.js" }, "type": "commonjs" }入口文件加上#!/usr/bin/env nodeshebang，用chmod +x bin/cli.js给可执行权限，之后就能在终端里直接运行了。
3.2 手写参数解析器（核心代码）
整个框架最核心的是参数解析器，我把它放在lib/parser.js里，贴出完整代码：
function coerce(raw, type) { switch (type) { case "number": return Number(raw); case "boolean": return raw === "true" || raw === true; case "array": return String(raw).split(","); default: return String(raw); } } function parseArgs(argv, cmd) { const values = {}; const errors = []; if (cmd.arguments) { const positionalTokens = argv.filter((t) => !t.startsWith("--")); cmd.arguments.forEach((arg, i) => { const v = positionalTokens[i]; if (v === undefined) { if (arg.required) { errors.push(`缺少参数 <${arg.name}>`); } } else { values[arg.name] = coerce(v, arg.type); } }); } for (let i = 0; i < argv.length; i++) { const t = argv[i]; if (!t.startsWith("--")) continue; const eq = t.indexOf("="); let key; let rawVal; if (eq !== -1) { key = t.slice(2, eq); rawVal = t.slice(eq + 1); } else { key = t.slice(2); const next = argv[i + 1]; if (next && !next.startsWith("--")) { rawVal = next; i++; } else { rawVal = "true"; } } const opt = (cmd.options || []).find((o) => o.name === key); if (!opt) { errors.push(`未知选项 --${key}`); continue; } values[key] = coerce(rawVal, opt.type); } for (const opt of cmd.options || []) { if (values[opt.name] === undefined && opt.default !== undefined) { values[opt.name] = opt.default; } if (opt.enum && values[opt.name] !== undefined && !opt.enum.includes(values[opt.name])) { errors.push(`选项 --${opt.name} 必须是 ${opt.enum.join("/")} 之一`); } } return { values, errors }; } module.exports = { parseArgs };这段代码有三个地方值得反复看。
第一个是位置参数的提取方式：argv.filter((t) => !t.startsWith("--"))。这是最小实现，能跑通但不够严谨，因为选项的值如果恰好不以--开头，也会被当成位置参数处理。我后面会在“常见问题”章节专门讲这个边界情况。
第二个是选项值的获取逻辑：优先看=显式赋值，拿不到就看下一个 token 是不是一个普通值，不是的话就按 boolean 处理。这就能支持--watch这种开关型选项。
第三个是默认值和枚举校验放在最后统一做。这保证了“用户传了值就尊重用户，没传值才用默认”，而且可以在一个循环里完成所有选项的最终状态确认。
3.3 注册第一个真实命令：Markdown 批量转 HTML
框架有了解析器，下一步注册一个真实命令。我选了“批量把 Markdown 转成 HTML”这个场景，因为它在日常写作和文档维护中太常见了。
配置文件cli-anything.json：
{ "name": "demo", "description": "CLI-Anything 演示工具", "commands": [ { "name": "md2html", "description": "把目录下的 Markdown 批量转成 HTML", "arguments": [ { "name": "input", "type": "string", "required": true, "description": "Markdown 文件目录" } ], "options": [ { "name": "output", "type": "string", "default": "dist", "description": "输出目录" }, { "name": "watch", "type": "boolean", "default": false, "description": "是否监听文件变化" } ], "handler": "commands/md2html.js" } ] }对应的 handler 写在commands/md2html.js：
const fs = require("fs"); const path = require("path"); module.exports = async function ({ values }) { const inputDir = path.resolve(values.input); const outputDir = path.resolve(values.output || "dist"); fs.mkdirSync(outputDir, { recursive: true }); const files = fs.readdirSync(inputDir).filter((f) => f.endsWith(".md")); if (files.length === 0) { console.log("没有找到 Markdown 文件"); return; } files.forEach((file, index) => { const md = fs.readFileSync(path.join(inputDir, file), "utf-8"); const html = render(md); const outFile = path.join(outputDir, file.replace(/\.md$/, ".html")); fs.writeFileSync(outFile, html); process.stdout.write(`[${index + 1}/${files.length}] ${file} -> ${outFile}\n`); }); }; function render(md) { return md .replace(/^### (.*)$/gm, "<h3>$1</h3>") .replace(/^## (.*)$/gm, "<h2>$1</h2>") .replace(/^# (.*)$/gm, "<h1>$1</h1>") .replace(/\*\*(.*?)\*\*/g, "<strong>$1</strong>"); }render函数是一个最小实现，只处理了标题和加粗，别拿去生产环境用，真要生产环境直接用 marked 或 unified 处理更靠谱。这里重点是看 handler 的写法：结构就是“拿到 values，干活，输出结果”。每个文件的处理进度直接写到 stdout，而不是用 console.log，这是有意为之——后面接管道或者重定向日志时，stdout 和 stderr 不会互相污染。
入口文件bin/cli.js把整个执行链串起来：
#!/usr/bin/env node const path = require("path"); const { loadConfig } = require("../lib/loader"); const { buildRegistry } = require("../lib/registry"); const { parseArgs } = require("../lib/parser"); const { runHandler } = require("../lib/runner"); const configPath = process.argv[2] === "--config" ? process.argv[3] : "./cli-anything.json"; const argv = process.argv.slice(2); const config = loadConfig(configPath); const registry = buildRegistry(config); if (argv.includes("--help") || argv.includes("-h")) { for (const cmd of config.commands) { console.log(`${cmd.name}\t${cmd.description}`); } process.exit(0); } const route = registry.match(argv); if (!route) { console.error("命令不存在，使用 --help 查看所有可用命令"); process.exit(2); } const parsed = parseArgs(argv, route); if (parsed.errors.length > 0) { console.error(parsed.errors.join("\n")); process.exit(1); } runHandler(route, parsed.values).catch((err) => { console.error(err.message || err); process.exit(1); });执行引擎lib/runner.js负责加载 handler 并调用：
const path = require("path"); async function runHandler(route, values) { const handlerPath = path.resolve(process.cwd(), route.handler); const handler = require(handlerPath); await handler({ values, cwd: process.cwd() }); } module.exports = { runHandler };到此，一个最小可用的 CLI-Anything 就跑起来了。执行效果：
$ node bin/cli.js md2html ./docs --output ./site [1/3] intro.md -> /site/intro.html [2/3] guide.md -> /site/guide.html [3/3] api.md -> /site/api.html3.4 交互体验：进度条、着色与退出码
上面的版本能输出进度信息，但还不够“现代 CLI”的感觉。接下来补上两个关键体验：进度条和退出码语义。
进度条的核心是“单行刷新”。用\r回到行首，覆盖写当前行内容，就能实现原地刷新效果：
function renderProgress(current, total) { const width = 30; const done = Math.floor((current / total) * width); const bar = "█".repeat(done) + "░".repeat(width - done); const percent = Math.round((current / total) * 100); process.stdout.write(`\r处理中 [${bar}] ${percent}%`); if (current === total) { process.stdout.write("\n"); } }注意两点：第一，输出完最后一项要补一个\n，否则下一个 shell 提示符会和进度条挤在同一行。第二，如果当前环境不是 TTY，比如 CI 里跑，就别输出那种带\r的进度条，直接退化成普通日志即可。判断方法就是process.stdout.isTTY。
退出码的事看起来小，实际很重要。我在 CLI-Anything 里定了三种：0 成功，1 参数错误或运行时错误，2 命令未找到。这个语义和很多系统工具是一致的，CI 脚本拿到非 0 退出码就能判断失败。关于异常处理，我建议只把“业务错误”打到 stderr，像库函数抛出的堆栈，除非设置了--verbose或环境变量DEBUG=1，否则不要默认打印完整堆栈。用户看到一堆 Intrinsic TypeError 只会觉得这个工具很烂。
4. 真实项目里的血泪坑：问题排查与速查表
4.1 数字参数与负数：被忽略的解析陷阱
参数解析里最常见的坑，是负数被当成新的选项。比如你有一个命令ca scale --count -1，解析器遍历到--count后面，看到下一个 token 是-1，如果判断条件写的是“不以--开头就当值”，那-1会被当成值的候选，但如果你写的是“以-开头就跳过”，--count就会变成 boolean，而-1变成了未知选项。
我踩过坑之后给出的解法分两步：一是在解析选项时判断“如果选项类型是 number，并且下一个 token 能通过Number()转换，就把它当作值”，而不是看它是否以--开头。二是给用户提供=的形式作为逃生通道，--count=-1永远不会被误判。我在 CLI-Anything 里两者都支持：解析时优先聪明识别，用户侧提供稳定写法兜底。这个设计让我以后再也没被负数问题坑过。
4.2 stdin 未消费导致的“幽灵挂起”
遇到过最诡异的一个问题是：命令执行完了，但进程就是不退出。排查了半天，发现是 handler 里某个逻辑读取了 stdin，但没消费完，Node 的事件循环被挂起的流监听一直占着，进程没法自然结束。
出现这个问题的场景通常是这样：某个 handler 里写了process.stdin.on("data", ...)来支持交互输入，但命令执行的路径没有走到关闭流的逻辑。解决办法很简单：只有真正需要交互输入时才去监听 stdin，用完立即process.stdin.pause()或者process.stdin.destroy()。如果你只是偶尔需要从管道读数据，建议统一提供一个readStdin()辅助函数，内部消费完数据后立刻释放，避免每个 handler 都自己折腾流。
4.3 异常处理与退出码：管道的体面
handler 里调用一个不存在的路径，fs.readFileSync会直接抛异常。如果没有统一捕获，Node 会把堆栈打到 stderr，并且退出码变成 1，这在终端看问题不大，但 CI 日志会被几百行堆栈淹没，真正的错误原因反而看不出来。
CLI-Anything 的解法是在入口处加一层全局 catch，把异常信息收敛成一行。用户想看详细堆栈，可以通过环境变量DEBUG=1打开。另外有个细节：不要在 catch 之后直接process.exit(1)，而应该先设置process.exitCode = 1，然后让进程自然结束。这样做的好处是，stdout 里可能还有一些未写完的数据可以正常冲刷出去，不至于截断半行输出。
还有一个管道场景的经典问题：你执行ca md2html ./docs | head -5，如果输出足够多，head提前关闭了管道，你这边再写 stdout 就会触发EPIPE错误。解决办法是在进程级忽略这个错误：process.stdout.on("error", (err) => { if (err.code === "EPIPE") process.exit(0); });。不然你的命令会因为一个无害的管道关闭而报红。
4.4 跨平台兼容：Windows 用户的眼泪
命令行工具天然容易踩跨平台坑。第一是路径分隔符，path.join和path.resolve能自动处理，但如果你手写了字符串拼接路径，在 Windows 上就会炸。第二是环境变量，bash 里FOO=bar ca foo这种写法在 Windows 的 cmd 里完全不支持，建议工具内部只读取process.env，由用户在各自的 shell 里管理环境变量。第三是删除文件，很多脚本喜欢直接映射rm -rf，这在 Windows 下会失败，建议用 Node 的fs.rm并传recursive: true, force: true。
还有一个不太容易注意的点：可执行文件的 shebang。在 Linux/macOS 上chmod +x之后可以直接跑，但 Windows 下靠的是系统关联 Node.exe，通常要用户自己配置。CLI-Anything 里我很早就接受了这个现实，文档里直接写明“Windows 用户请通过node bin/cli.js运行”，或者装一个 shim，不要在框架层面浪费太多精力去搞跨平台启动器。
4.5 排查速查表
最后把上面所有问题整理成一张速查表，方便你遇到问题时直接对照。
| 现象 | 常见原因 | 解决办法 |
|---|---|---|
--count -1解析失败 | 解析器把-1当成选项 | number 类型下尝试Number()转换，或提示用户用--count=-1 |
| 命令执行完毕但进程不退出 | stdin 流未消费或未关闭 | 用完即pause()/destroy()，提供统一readStdin() |
命令偶发报EPIPE | 下游head/grep提前关闭管道 | 监听 stdout 的 error，忽略EPIPE异常 |
| Windows 下 handler 路径找不到 | 手写路径分隔符或rm -rf用法 | 用path.join/fs.rm，避免 shell 特有语法 |
| CI 日志里堆栈过载 | 未统一 catch 异常 | 全局 catch，默认打印单行错误，DEBUG=1开堆栈 |
--help被当成命令 | 路由查找优先于 help 判断 | 进入命令路由前先检查-h/--help |
boolean 选项传--watch false不生效 | 解析器把false当作值，coerce 后变成 true | boolean 类型不要紧跟在false后，使用--watch=false或只做开关 |
我在实际使用中最深的体会是：CLI 工具的“小”是相对的，它看起来只有几段代码，但做好之后对工作效率的提升是全方位的。CLI-Anything 这个项目让我把原来那些没人敢碰的脚本，慢慢变成了团队里人人能用的标准工具。
前阵子我还给它加了一个很实用的扩展：根据配置文件自动生成 Zsh 补全脚本。原理不复杂，遍历命令树，把参数和选项转成_arguments规范输出到补全文件。这个功能上线之后，连我那个从不用终端的同事都开始主动敲 Tab 了。这大概就是做命令行工具最值得的一刻——你写的框架真正降低了别人使用命令行的门槛。如果你也在维护一堆脚本，不妨试试这种“描述优先”的设计思路，先从一个小命令开始，你会很快感受到它的价值。
