在实际开发工作中我们经常需要为内部工具、自动化脚本或服务接口编写命令行界面CLI。从零开始构建一个功能完善、体验良好的 CLI 往往涉及参数解析、帮助文档生成、子命令管理、颜色输出、交互式提示等大量重复性工作。有没有一种工具能让我们像使用脚手架一样快速“生产”出结构规范、功能完备的 CLI 应用呢这正是Show HN: CLI to Churn Out CLIs这个项目所瞄准的痛点。它本质上是一个用于生成 CLI 的 CLI 工具旨在将开发者从繁琐的 CLI 框架搭建中解放出来专注于核心业务逻辑的实现。本文将带你深入理解这类“CLI 生成器”的核心价值、工作原理并手把手演示如何从零开始构思、设计并实现一个属于自己的简易版 CLI 生成工具。我们将使用 Node.js 环境因为它拥有丰富的生态和成熟的 CLI 开发库。通过本文你将掌握 CLI 应用的标准结构、核心库的选择以及如何设计一个可扩展的生成器。最终你将得到一个能够根据模板快速生成 CLI 项目骨架的工具并能将其思路应用到 Python、Go 等其他语言生态中。1. 理解 CLI 生成器的核心价值与设计思路在动手之前我们需要明确一个优秀的 CLI 生成器到底解决了什么问题以及它内部应该如何工作。1.1 为什么需要 CLI 生成器手动创建一个新的 CLI 项目通常需要经历以下步骤初始化项目npm init,go mod init等。安装核心依赖如commander,yargs,cobra。创建入口文件如bin/cli.js,cmd/root.go。编写基础的参数解析、帮助命令和版本命令。配置package.json或go.mod中的二进制文件路径。设置开发环境如 ESLint、Prettier、测试框架。这些步骤虽然不复杂但重复且容易出错。CLI 生成器的价值在于标准化确保团队内所有 CLI 项目具有一致的结构、代码风格和工具链。提效将几分钟甚至十几分钟的初始化工作缩短到几秒钟。最佳实践内置自动集成日志、错误处理、配置加载等常见模式。降低门槛让不熟悉 CLI 开发细节的开发者也能快速产出高质量工具。1.2 一个 CLI 生成器应包含哪些模块一个功能完整的 CLI 生成器其自身也是一个 CLI 应用。它的核心工作流程如下用户输入生成命令 - 解析用户选项项目名、语言、特性- 选择对应模板 - 渲染模板文件到目标目录 - 执行后置操作安装依赖、初始化 Git因此它的内部通常包含以下模块模块职责关键技术点命令解析解析create project-name等命令和--template,--yes等选项。使用commander、yargs或inquirer交互式。模板管理存储不同项目类型基础 CLI、带子命令的 CLI、特定框架 CLI的模板文件。模板可以是文件目录使用ejs、handlebars等模板引擎渲染变量。文件操作创建目标目录将模板文件复制/渲染到正确位置。使用fs-extra增强文件操作注意处理路径和文件覆盖问题。交互与配置询问用户项目名称、描述、特性选择等或读取预设配置。使用inquirer进行交互式提问使用cosmiconfig读取全局配置。依赖安装在项目生成后自动运行npm install或go mod tidy。使用execa或child_process模块执行子进程命令。日志与反馈向用户清晰展示生成进度、成功信息或错误提示。使用chalk输出彩色文字ora显示加载动画。理解了这些我们就可以开始动手搭建了。2. 环境准备与项目初始化我们将使用 Node.js 来构建这个生成器。首先确保你的开发环境符合要求。2.1 环境检查清单在开始前请确认以下环境已就绪项目要求检查命令Node.jsLTS 版本如 18.x, 20.xnode --versionnpm通常随 Node.js 安装npm --version代码编辑器VSCode 或其他-终端Bash, Zsh, PowerShell 等-如果未安装 Node.js请从官网下载并安装 LTS 版本。2.2 初始化生成器项目本身我们的第一个 CLI就是用来生成其他 CLI 的生成器。让我们先创建它。# 1. 创建一个新目录作为生成器项目 mkdir cli-generator cd cli-generator # 2. 初始化 npm 项目一路回车或按需填写 npm init -y # 3. 创建基础目录结构 mkdir -p src/templates/basic-cli初始化后的package.json文件内容大致如下{ name: cli-generator, version: 1.0.0, description: A CLI tool to generate CLI projects, main: index.js, scripts: { test: echo \Error: no test specified\ exit 1 }, keywords: [], author: , license: ISC }2.3 安装核心依赖我们将安装实现生成器所需的关键库。# 安装依赖 npm install commander inquirer chalk ora fs-extra ejs # 安装开发依赖用于代码质量和构建 npm install --save-dev eslint prettier types/node各依赖库的作用说明库名用途commander解析命令行参数和定义命令。inquirer提供交互式命令行问答界面。chalk为终端输出添加颜色提升可读性。ora显示优雅的加载中动画。fs-extra增强版fs模块提供更便捷的文件系统操作。ejs嵌入式 JavaScript 模板引擎用于渲染模板中的变量。3. 构建 CLI 生成器的核心逻辑现在我们来编写生成器本身的代码。我们将创建一个支持create name命令的生成器。3.1 创建入口文件与命令解析在项目根目录创建bin/cli.js文件作为我们生成器的入口。#!/usr/bin/env node // 上面这行是 shebang告诉系统用 Node.js 来执行此脚本 const { program } require(commander); const create require(../src/commands/create); program .name(cli-gen) // 你的生成器命令名 .description(A CLI tool to generate standardized CLI projects) .version(1.0.0); // 定义 create 命令 program .command(create project-name) .description(Create a new CLI project) .option(-t, --template template-name, Specify a template (basic, advanced), basic) .option(-y, --yes, Use default options without prompt, false) .action((projectName, options) { create(projectName, options); }); program.parse(process.argv);接下来修改package.json指定入口和二进制命令。{ name: cli-generator, version: 1.0.0, description: A CLI tool to generate CLI projects, main: bin/cli.js, bin: { cli-gen: ./bin/cli.js }, scripts: { test: echo \Error: no test specified\ exit 1 }, dependencies: { chalk: ^4.1.2, commander: ^11.0.0, ejs: ^3.1.9, fs-extra: ^11.1.1, inquirer: ^8.2.6, ora: ^5.4.1 }, devDependencies: { eslint: ^8.0.0, prettier: ^3.0.0, types/node: ^20.0.0 }, keywords: [], author: , license: ISC }现在你可以在本地链接这个命令进行测试# 在 cli-generator 项目根目录执行 npm link # 执行后全局就可以使用 cli-gen 命令了 cli-gen --help你应该能看到create命令的帮助信息。3.2 实现create命令的核心逻辑创建src/commands/create.js文件这是生成逻辑的核心。const path require(path); const fs require(fs-extra); const inquirer require(inquirer); const chalk require(chalk); const ora require(ora); module.exports async function create(projectName, options) { const cwd process.cwd(); // 当前命令行所在目录 const targetDir path.join(cwd, projectName); // 目标项目目录 // 1. 检查目标目录是否已存在 if (fs.existsSync(targetDir)) { const { action } await inquirer.prompt([ { name: action, type: list, message: Directory ${chalk.cyan(projectName)} already exists. Pick an action:, choices: [ { name: Overwrite, value: overwrite }, { name: Merge, value: merge }, { name: Cancel, value: false } ] } ]); if (!action) { console.log(chalk.yellow(Operation cancelled.)); return; } else if (action overwrite) { console.log(chalk.yellow(\nRemoving ${chalk.cyan(projectName)}...)); await fs.remove(targetDir); } // 如果是 merge则继续文件可能会被覆盖 } // 2. 收集项目信息如果未使用 -y 选项 let answers {}; if (!options.yes) { answers await inquirer.prompt([ { name: projectDescription, type: input, message: Please enter a description for your CLI:, default: A awesome CLI tool }, { name: author, type: input, message: Author:, default: }, { name: license, type: input, message: License:, default: MIT }, { name: useEslint, type: confirm, message: Do you want to use ESLint for code linting?, default: true }, { name: usePrettier, type: confirm, message: Do you want to use Prettier for code formatting?, default: true } ]); } else { // 使用默认值 answers { projectDescription: A awesome CLI tool, author: , license: MIT, useEslint: true, usePrettier: true }; } // 3. 准备模板数据 const templateData { projectName, projectDescription: answers.projectDescription, author: answers.author, license: answers.license, useEslint: answers.useEslint, usePrettier: answers.usePrettier }; // 4. 确定模板路径这里我们只实现一个基础模板 const templateDir path.join(__dirname, ../templates/${options.template}); if (!fs.existsSync(templateDir)) { console.log(chalk.red(Template ${options.template} not found.)); return; } // 5. 创建项目目录并渲染模板 const spinner ora(Creating project in ${chalk.green(targetDir)}...).start(); try { await fs.ensureDir(targetDir); // 确保目录存在 await copyAndRender(templateDir, targetDir, templateData); spinner.succeed(chalk.green(Project created successfully!)); } catch (error) { spinner.fail(chalk.red(Failed to create project.)); console.error(chalk.red(error.message)); // 如果创建失败尝试清理已创建的目录 if (fs.existsSync(targetDir)) { await fs.remove(targetDir); } process.exit(1); } // 6. 后续指引 console.log(\n${chalk.cyan(Next steps:)}); console.log( cd ${projectName}); console.log( npm install); console.log( npm link # To test your new CLI locally); console.log(\nHappy hacking!); }; // 辅助函数复制并渲染模板 async function copyAndRender(src, dest, data) { const files await fs.readdir(src); for (const file of files) { const srcFile path.join(src, file); const destFile path.join(dest, file); const stat await fs.stat(srcFile); if (stat.isDirectory()) { await fs.ensureDir(destFile); await copyAndRender(srcFile, destFile, data); } else { let content await fs.readFile(srcFile, utf-8); // 如果文件是 .ejs 模板则渲染 if (file.endsWith(.ejs)) { const ejs require(ejs); content ejs.render(content, data); // 移除 .ejs 扩展名 await fs.writeFile(destFile.replace(/\.ejs$/, ), content); } else { // 普通文件直接复制 await fs.copy(srcFile, destFile); } } } }3.3 创建基础 CLI 模板现在我们需要创建被生成的 CLI 项目的模板。在src/templates/basic-cli/目录下创建以下文件。1.package.json.ejs(模板文件){ name: % projectName %, version: 1.0.0, description: % projectDescription %, main: index.js, bin: { % projectName %: ./bin/cli.js }, scripts: { start: node ./bin/cli.js, test: echo \Error: no test specified\ exit 1% if (useEslint) { %, lint: eslint .% } %% if (usePrettier) { %, format: prettier --write .% } % }, keywords: [cli], author: % author %, license: % license %, dependencies: { commander: ^11.0.0, chalk: ^4.1.2 }% if (useEslint) { %, devDependencies: { eslint: ^8.0.0 }% } %% if (usePrettier) { %, devDependencies: { prettier: ^3.0.0 }% } % }2.bin/cli.js.ejs(模板文件)#!/usr/bin/env node const { program } require(commander); const chalk require(chalk); program .name(% projectName %) .description(% projectDescription %) .version(1.0.0); program .command(hello) .description(Say hello) .action(() { console.log(chalk.green(Hello from your new CLI!)); }); program.parse(process.argv);3..gitignore(普通文件)node_modules/ *.log .DS_Store4.README.md.ejs(模板文件)# % projectName % % projectDescription % ## Installation bash npm install -g . # or npm linkUsage% projectName % --help % projectName % hello至此我们的 CLI 生成器已经具备了核心功能。你可以运行 cli-gen create my-new-cli 来测试它。 ## 4. 运行验证与结果分析 让我们完整地走一遍流程验证生成器是否按预期工作。 ### 4.1 测试生成流程 在终端中执行以下命令 bash # 确保你已在 cli-generator 目录下并且已执行过 npm link cli-gen create demo-cli你会看到交互式提问依次回答或使用默认值。完成后进入生成的项目目录查看。cd demo-cli ls -la你应该能看到类似如下的结构. ├── bin │ └── cli.js ├── package.json ├── README.md └── .gitignore4.2 验证生成的 CLI 是否可运行# 在 demo-cli 目录下安装依赖 npm install # 将生成的 CLI 链接到全局方便测试 npm link # 现在你可以像使用任何全局 CLI 一样使用它 demo-cli --help demo-cli hello执行demo-cli hello应该会输出绿色的 “Hello from your new CLI!” 文字。4.3 关键文件内容检查打开demo-cli/package.json检查模板变量是否被正确替换{ name: demo-cli, description: 你输入或默认的描述, bin: { demo-cli: ./bin/cli.js }, // ... 其他字段也应被正确渲染 }打开demo-cli/bin/cli.js检查程序名和描述是否正确program .name(demo-cli) // 注意这里 .description(你输入或默认的描述) // 注意这里如果以上检查都通过说明你的 CLI 生成器工作正常。5. 常见问题排查与优化在实际使用中你可能会遇到一些问题。下面列出常见问题及其解决方案。5.1 生成器命令未找到或无法执行问题现象可能原因检查与解决执行cli-gen提示command not found1. 未在生成器项目目录执行npm link。2. 全局node_modules/.bin目录不在系统 PATH 中。1. 确保在cli-generator根目录运行了npm link。2. 检查npm config get prefix确保该路径下的bin目录在 PATH 中。执行cli-gen提示Permission denied脚本文件没有执行权限。为bin/cli.js添加执行权限chmod x bin/cli.js然后重新npm link。执行生成的 CLI 命令如demo-cli无效未在生成的 CLI 项目目录执行npm install和npm link。确保在生成的项目目录中运行了npm install并且使用npm link将其注册到全局。5.2 模板渲染错误或文件缺失问题现象可能原因检查与解决生成的package.json中变量未被替换仍是% ... %。1. 模板文件扩展名不是.ejs。2.copyAndRender函数中处理.ejs文件的逻辑有误。1. 确认模板文件命名正确如package.json.ejs。2. 检查copyAndRender函数中读取、渲染、重命名文件的代码逻辑。生成的项目缺少某些文件。1. 模板目录路径错误。2. 文件复制过程中出现异常被静默忽略。1. 检查create.js中templateDir的拼接逻辑。2. 在copyAndRender函数中添加console.log调试或使用try-catch包裹并打印具体错误。生成时出现EJS语法错误。模板文件中存在错误的 EJS 语法。检查模板文件确保% %,% %等标签正确闭合且引用的变量名在templateData中存在。5.3 依赖安装失败或版本冲突问题现象可能原因检查与解决在生成的项目中运行npm install失败。1. 网络问题。2.package.json中依赖版本号指定过于严格或不存在。1. 检查网络连接或尝试使用国内镜像源。2. 在模板的package.json.ejs中将依赖版本号改为较宽松的范围如^11.0.0。生成的 CLI 运行时提示Cannot find module commander。依赖未安装或生成的 CLI 未正确链接到其自身的node_modules。1. 确保在生成的项目目录中运行了npm install。2. 如果使用npm link测试确保链接正确。可以运行npm list -g --depth0查看全局链接。5.4 功能扩展与优化建议当前生成器只是一个最小可行产品MVP。要使其更实用可以考虑以下优化更多模板在src/templates/下创建advanced-cli模板包含子命令、配置管理、日志、错误处理等更复杂的结构。动态依赖根据用户选择如是否需要inquirer、ora动态调整package.json中的dependencies。Git 初始化生成完成后自动执行git init和初始提交。配置持久化使用cosmiconfig读取用户全局配置文件如~/.cligenrc保存默认作者名、常用许可证等避免每次询问。更友好的交互使用inquirer的复选框、搜索列表等高级组件让用户选择要集成的功能模块。后置钩子Hooks支持在文件复制完成后执行自定义脚本如运行npm run lint -- --fix。单元测试为生成器本身添加单元测试确保模板渲染和文件操作逻辑正确。6. 生产环境考量与最佳实践如果你计划将这个生成器用于团队或发布到 npm以下是一些生产级的最佳实践。6.1 安全性文件操作安全在覆盖或删除目录前务必明确提示用户。我们的代码中已经通过inquirer做了确认。模板来源安全如果支持从远程仓库Git拉取模板务必验证仓库地址和内容避免执行恶意脚本。依赖安全定期更新生成器自身及其模板中的依赖版本如commander,chalk使用npm audit检查漏洞。6.2 可维护性模板结构化将模板按类型、语言Node.js, Python, Go清晰分类。配置外置将模板变量、默认选项等抽离到独立的配置文件如config/templates.json中便于管理。日志与错误处理使用winston或pino等日志库替代console.log对不同级别INFO, WARN, ERROR的信息进行区分和记录。编写测试为模板渲染逻辑、文件操作函数编写单元测试和集成测试。6.3 用户体验进度反馈像我们使用ora一样对于耗时操作如下载、安装提供明确的进度提示。丰富的命令行选项支持--dry-run干跑模式只展示将要执行的操作而不实际执行。清晰的文档为你的生成器编写详细的README.md说明所有命令、选项和模板。版本管理遵循语义化版本控制SemVer当模板有破坏性更新时升级主版本号。6.4 发布到 npm如果你希望他人也能使用你的生成器可以将其发布到 npm 仓库。完善package.json填写详细的description,keywords,repository,bugs,homepage字段。指定files字段控制发布到 npm 的文件范围避免将测试文件、模板源文件等不必要的内容发布出去。files: [ bin/, src/, README.md, LICENSE ]添加prepublishOnly脚本确保在发布前运行测试和构建如果有构建步骤。scripts: { prepublishOnly: npm test }登录并发布npm login npm publish发布后用户就可以通过npm install -g your-cli-generator-name来安装并使用它了。通过以上步骤你不仅实现了一个可用的 CLI 生成器更掌握了一套构建标准化开发工具的方法论。这种“元工具”的开发思路可以极大地提升团队的工具链效率和项目一致性。你可以尝试用同样的思路为你的技术栈打造前端项目生成器、微服务脚手架、数据库迁移工具等将重复的初始化工作彻底自动化。