当前位置：首页 > news >正文

前端架构: 脚手架框架之yargs的11种基础核心特性的应用教程

news 2025/7/8 22:50:45

脚手架框架之yargs的基础核心特性与应用

1 ）概述

yargs 是脚手架当中使用量非常大的一个框架
进入它的npm官网: https://www.npmjs.com/package/yargs
- 目前版本: 17.7.2
- Weekly Downloads: 71,574,188 (动态数据)
- 最近更新：last month (github)
- 说明这是一个比较优质的库

2 ）对 yargs 的应用

准备一个脚手架工程，比如 xyzcli
进行 npm 初始化 $ npm init -y
修改package.json中的关键配置
- 添加 bin 属性，其值设置为: “bin/index.js”
在脚手架工程目录中执行安装开发依赖
- $ npm i yargs -S

2.1 初步实践，了解其基本API

编写 bin/index.js

#!/usr/bin/env nodeconst yargs = require('yargs/yargs');
const { hideBin } = require('yargs/helpers');
console.log(hideBin(process.argv));
yargs();

现在执行 $ npm link 方便调试
执行 $ xyzcli --help, 可以看到输出 [ '--help' ]

2.2 继续优化，窥探其基本用法

好，接着修改 bin/index.js

#!/usr/bin/env nodeconst yargs = require('yargs/yargs');
const { hideBin } = require('yargs/helpers'); // 用于参数解析
const arg = hideBin(process.argv);yargs(arg).argv;

现在执行 $ xyzcli --help 可以看到输出

选项：--help     显示帮助信息                                                 [布尔]--version  显示版本号                                                   [布尔]

执行 $ xyzcli --version
```
1.0.0
```
这时候说明最简易版脚手架已经开发好了

2.3 探究 strict 模式

现在发现差异，如果执行 $ xyzcli --help 有输出
但是执行 $ xyzcli -h 就没有输出了
可以加入 strict 模式，可以对无用参数输入进行提示，如下添加
```
yargs(arg).strict().argv;
```

继续执行 $ xyzcli -h 看到输出了报错提示

选项：--help     显示帮助信息                                                 [布尔]--version  显示版本号                                                   [布尔]无法识别的选项：h

注意这个 strict 在 lerna 源码中有用到

2.4 对 usage 这个API的使用

继续测试 usage

yargs(arg).usage('Usage: xyzcli [command] <options>').strict().argv;

执行 $ xyzcli --help，查看输出

Usage: xyzcli [command] <options>选项：--help     显示帮助信息                                                 [布尔]--version  显示版本号                                                   [布尔]

看到，最顶部多了 Usage: xyzcli [command] <options>

2.5 对 demandCommand 这个API的使用

这个API表示最少输入多少命令

yargs(arg).usage('Usage: xyzcli [command] <options>').demandCommand(1, 'A command is required. Pass --help to see all available commands and options.').strict().argv;

只执行 $ xyzcli, 可查看输出

Usage: xyzcli [command] <options>选项：--help     显示帮助信息                                                 [布尔]--version  显示版本号                                                   [布尔]A command is required. Pass --help to see all available commands and options.

可以发现，最后多了一行 A command is required. Pass --help to see all available commands and options.
这个API就可以对命令参数过少时进行提示

2.6 对 alias 这个API的使用

对现有命令或参数起别名

yargs(arg).usage('Usage: xyzcli [command] <options>').demandCommand(1, 'A command is required. Pass --help to see all available commands and options.').strict().alias('h', 'help').alias('v', 'version').argv;

对 -h 进行测试，执行 $ xyzcli -h，输出

Usage: xyzcli [command] <options>选项：-h, --help     显示帮助信息                                             [布尔]-v, --version  显示版本号                                               [布尔]

对 -v 进行测试，执行 $ xyzcli -v，输出
```
1.0.0
```

2.7 对 wrap 这个API的使用

对终端cli窗口的宽度的设定

yargs(arg).usage('Usage: xyzcli [command] <options>').demandCommand(1, 'A command is required. Pass --help to see all available commands and options.').strict().alias('h', 'help').alias('v', 'version').wrap(50) // 这里设定为 50.argv;

执行 $ xyzcli -h，查看宽度

Usage: xyzcli [command] <options>选项：-h, --help     显示帮助信息               [布尔]-v, --version  显示版本号                 [布尔]

修改宽度为 80
```
.wrap(80) // 这里设定为 80
```

再次执行 $ xyzcli -h，查看宽度

Usage: xyzcli [command] <options>选项：-h, --help     显示帮助信息                                             [布尔]-v, --version  显示版本号                                               [布尔]

可以看到两者不同宽度的区别

如果想要占满终端屏幕, 可以使用 terminalWidth()

const cli = yargs(arg)cli.usage('Usage: xyzcli [command] <options>').demandCommand(1, 'A command is required. Pass --help to see all available commands and options.').strict().alias('h', 'help').alias('v', 'version').wrap(cli.terminalWidth()) // 这里.argv;

terminalWidth() 会返回终端宽度，这里没有必要做演示了，会铺满终端

2.8 对 epilogue 这个API的使用

它可以在结尾加上我们想要说的话

const cli = yargs(arg)cli.usage('Usage: xyzcli [command] <options>').demandCommand(1, 'A command is required. Pass --help to see all available commands and options.').strict().alias('h', 'help').alias('v', 'version').wrap(cli.terminalWidth()).epilogue('We hope you guys work happily every day!') // 注意这里.argv;

执行 $ xyzcli -h, 查看输出

Usage: xyzcli [command] <options>选项：-h, --help     显示帮助信息                                                                  [布尔]-v, --version  显示版本号                                                                    [布尔]We hope you guys work happily every day!

可以看到最后一行，输出 We hope you guys work happily every day!
结合 dedent 库来使用，首先进行安装，$ npm i dedent -S

基于 dedent 库来设定 epilogue, 达成去除缩进(包含首位空格)的目的

#!/usr/bin/env nodeconst yargs = require('yargs/yargs');
const { hideBin } = require('yargs/helpers');
const dedent = require('dedent'); // 注意这里const arg = hideBin(process.argv);
const cli = yargs(arg)cli.usage('Usage: xyzcli [command] <options>').demandCommand(1, 'A command is required. Pass --help to see all available commands and options.').strict().alias('h', 'help').alias('v', 'version').wrap(cli.terminalWidth()).epilogue(dedent`Welcome to use xyzcli command line.We hope you guys work happily every day!For more information, please visit: https://xxx.com/xxx/xyzcli`).argv;

执行 $ xyzcli -h，查看输出

Usage: xyzcli [command] <options>选项：-h, --help     显示帮助信息                                                                  [布尔]-v, --version  显示版本号                                                                    [布尔]Welcome to use xyzcli command line.
We hope you guys work happily every day!For more information, please visit: https://xxx.com/xxx/xyzcli

2.9 对 options 这个API的使用

全局选项，对所有 command 都有效

const cli = yargs(arg)cli.usage('Usage: xyzcli [command] <options>').demandCommand(1, 'A command is required. Pass --help to see all available commands and options.').strict().alias('h', 'help').alias('v', 'version')// .alias('d', 'debug') // 这个设置别名，同下面，二者取其一即可.wrap(cli.terminalWidth()).epilogue(dedent`Welcome to use xyzcli command line.We hope you guys work happily every day!For more information, please visit: https://xxx.com/xxx/xyzcli`).options({debug: {type: 'boolean',describe: 'Bootstrap debug mode',alias: 'd' // 这里添加了，上面就可以忽略了，推荐写在这里}}).argv;

这里设置了 options，内部传入一个对象进行配置，这里别名的两种设置方式，推荐下面这种，在options内部设定

执行 $ xyzcli -h, 查看输出结果

Usage: xyzcli [command] <options>选项：-d, --debug    Bootstrap debug mode                                                          [布尔]-h, --help     显示帮助信息                                                                  [布尔]-v, --version  显示版本号                                                                    [布尔]Welcome to use xyzcli command line.
We hope you guys work happily every day!For more information, please visit: https://xxx.com/xxx/xyzcli

可见，这里添加了 -d 和 --debug 的选项

2.10 对 option 这个API的使用

这个 option 和 options 这两个API用途差不多, 但使用方式不一样

const cli = yargs(arg)cli.usage('Usage: xyzcli [command] <options>').demandCommand(1, 'A command is required. Pass --help to see all available commands and options.').strict().alias('h', 'help').alias('v', 'version')// .alias('d', 'debug').wrap(cli.terminalWidth()).epilogue(dedent`Welcome to use xyzcli command line.We hope you guys work happily every day!For more information, please visit: https://xxx.com/xxx/xyzcli`).options({debug: {type: 'boolean',describe: 'Bootstrap debug mode',alias: 'd' // 这里添加了，上面就可以忽略了，推荐写在这里}}).option('registry', {type: 'string',describe: 'Define global registry',alias: 'r',// hidden: true, // 这个就不会出现在提示中，但是可以作为开发调试使用 --registry 或 -r}).argv;

option 这个API，可以配置 hidden 选项，这个配置之后，不会出现在终端提示中，但是可作为开发调试使用，$ xyzcli -r
- 需要后期结合这个参数做对应的处理程序，这块先略过
- 同时，需注意，options 中是没有 hidden 配置选项的

执行 $ xyzcli -h，查看输出结果

Usage: xyzcli [command] <options>选项：-d, --debug     Bootstrap debug mode                                                         [布尔]-r, --registry  Define global registry                                                     [字符串]-h, --help      显示帮助信息                                                                 [布尔]-v, --version   显示版本号                                                                   [布尔]Welcome to use xyzcli command line.
We hope you guys work happily every day!For more information, please visit: https://xxx.com/xxx/xyzcliA command is required. Pass --help to see all available commands and options.

2.11 对 group 这个API的使用

对命令进行分组管理, 这次全量代码都在这里

#!/usr/bin/env nodeconst yargs = require('yargs/yargs');
const { hideBin } = require('yargs/helpers');
const dedent = require('dedent');const arg = hideBin(process.argv);
const cli = yargs(arg)cli.usage('Usage: xyzcli [command] <options>').demandCommand(1, 'A command is required. Pass --help to see all available commands and options.').strict().alias('h', 'help').alias('v', 'version')// .alias('d', 'debug').wrap(cli.terminalWidth()).epilogue(dedent`Welcome to use xyzcli command line.We hope you guys work happily every day!For more information, please visit: https://xxx.com/xxx/xyzcli`).options({debug: {type: 'boolean',describe: 'Bootstrap debug mode',alias: 'd' // 这里添加了，上面就可以忽略了，推荐写在这里}}).option('registry', {type: 'string',describe: 'Define global registry',alias: 'r',// hidden: true, // 这个就不会出现在提示中，但是可以作为开发调试使用 --ci}).group(['debug'], '开发选项：').group(['registry'], '其他选项：').argv;

执行 $ xyzcli -h，查看输出结果

Usage: xyzcli [command] <options>开发选项：-d, --debug  Bootstrap debug mode                                                            [布尔]其他选项：-r, --registry  Define global registry                                                     [字符串]选项：-h, --help     显示帮助信息                                                                  [布尔]-v, --version  显示版本号                                                                    [布尔]Welcome to use xyzcli command line.
We hope you guys work happily every day!For more information, please visit: https://xxx.com/xxx/xyzcli