CLI 工具
规则
- 参数解析:使用 Commander.js —
.command()、.option()、.argument() 并附上描述
- 交互式提示:使用
@clack/prompts(现代美观)或 inquirer — 当参数未提供时用于用户输入
- 加载动画:使用
ora 处理长时间运行的操作 — 启动、更新消息、成功/失败
- 颜色输出:使用
chalk 进行样式化输出 — 适度使用:红色表示错误,绿色表示成功,黄色表示警告,灰色表示次要信息
- 配置文件:使用
cosmiconfig — 自动搜索 .toolrc、.toolrc.json、tool.config.js、package.json 中的键
- 退出码:
0 表示成功,1 表示通用错误,2 表示用法错误 — 始终使用 process.exit(code)
--help 和 --version 标志:Commander 会自动添加 — 为每个选项编写清晰的描述
- 错误处理:在顶层捕获错误,向 stderr 打印用户友好的消息,以代码 1 退出
- 发布:在
package.json 中设置 bin 字段,添加 #!/usr/bin/env node shebang,设置 "type": "module" 以支持 ESM
模式
#!/usr/bin/env node
import { Command } from "commander";
import * as p from "@clack/prompts";
import ora from "ora";
import chalk from "chalk";
const program = new Command()
.name("my-tool")
.description("一个执行有用操作的 CLI 工具")
.version("1.0.0");
program
.command("init")
.description("初始化一个新项目")
.option("-t, --template <name>", "要使用的模板", "default")
.action(async (options) => {
p.intro(chalk.bold("项目设置"));
const name = await p.text({ message: "项目名称?", placeholder: "my-app" });
if (p.isCancel(name)) { p.cancel("已取消."); process.exit(0); }
const spinner = ora("正在创建项目...").start();
await createProject(name, options.template);
spinner.succeed(chalk.green("项目创建成功!"));
p.outro(`运行 ${chalk.cyan(`cd ${name} && npm install`)}`);
});
program.parse();
避免
- 将错误输出到 stdout — 应用
console.error() 或 process.stderr.write() 输出错误
- 失败时不带退出码退出 — 始终使用
process.exit(1),以便脚本和 CI 能够检测到失败
- 大段无格式文本 — 使用 chalk 颜色、分节和空白提高可读性
- 要求交互式输入而不提供标志替代方案 — 始终支持
--flag 覆盖选项以用于 CI/脚本环境
- 忘记 shebang
#!/usr/bin/env node — 没有它,npx 和全局安装将无法正常工作