# @gemini-testing/commander 中文文档

规范地址：https://npmcn.com/package/%40gemini-testing/commander/

版本：2\.15\.4
npm 元数据更新时间：2024-08-09T13:55:03.815Z
中文译文更新时间：2026-11-16T02:37:57.399Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40gemini-testing/commander
原文对照：https://npmcn.com/package/%40gemini-testing/commander/?lang=original
项目主页：https://github.com/gemini-testing/commander.js#readme
源码仓库：https://github.com/gemini-testing/commander.js

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：50.3 kB，5 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- 首次发布：2018-07-31T09:26:30.982Z
- 最新版本发布：2024-08-09T13:55:03.459Z
- 近 30 天下载量：20432（2026-10-16 至 2026-11-14，npm 官方下载统计）
- 已发布版本数：4（近 12 个月 0 个）

## 中文简介

用于节点.js命令行程序的完整解决方案

## 安装

```sh
npm install @gemini-testing/commander
```

也可以使用：`pnpm add @gemini-testing/commander`、`yarn add @gemini-testing/commander`、`bun add @gemini-testing/commander`

## README

# 指挥官.js

[![Build Status](https://api.travis-ci.org/tj/commander.js.svg?branch=master)](http://travis-ci.org/tj/commander.js) [![NPM Version](http://img.shields.io/npm/v/commander.svg?style=flat)](https://www.npmjs.org/package/commander) [![NPM Downloads](https://img.shields.io/npm/dm/commander.svg?style=flat)](https://npmcharts.com/compare/commander?minimal=true) [![Join the chat at https://gitter.im/tj/commander.js](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/tj/commander.js?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)

彻底解决 [节点.js](http://nodejs.org/) 命令行界面,灵感来自Ruby's [指挥官](https://github.com/commander-rb/commander)。 。 。 .  
[API 文档](http://tj.github.com/commander.js/)

## 安装

```
$ npm install commander --save
```

## 选项解析

带有命令的选项与 `.option()` 方法,也可作为选项的文档。 下面的示例从 `process.argv`中,留下剩余参数作为 `program.args` 未为选项所消耗的数组.

```js
#!/usr/bin/env node

/**
 * Module dependencies.
 */

var program = require('commander');

program
  .version('0.1.0')
  .option('-p, --peppers', 'Add peppers')
  .option('-P, --pineapple', 'Add pineapple')
  .option('-b, --bbq-sauce', 'Add bbq sauce')
  .option('-c, --cheese [type]', 'Add the specified type of cheese [marble]', 'marble')
  .parse(process.argv);

console.log('you ordered a pizza with:');
if (program.peppers) console.log('  - peppers');
if (program.pineapple) console.log('  - pineapple');
if (program.bbqSauce) console.log('  - bbq');
console.log('  - %s cheese', program.cheese);
```

例如, 短旗可以作为单一的坐标传递 `-abc` 等同为 `-a -b -c`. "--template-engine"等多词选项被骆驼套入,成为"--template-engine" `program.templateEngine` 包括:.

请注意,从 `--no` 前缀否定了以下单词的布尔值。 譬如说, `--no-sauce` 设置值 `program.sauce` 以假相报.

```js
#!/usr/bin/env node

/**
 * Module dependencies.
 */

var program = require('commander');

program
  .option('--no-sauce', 'Remove sauce')
  .parse(process.argv);

console.log('you ordered a pizza');
if (program.sauce) console.log('  with sauce');
else console.log(' without sauce');
```

## 版本选项

呼叫电话 `version` 隐含地添加 `-V` 财务报告和审定财务报表 `--version` 选项. 当其中任一选项出现时,命令会打印出版本编号并退出.

```
$ ./examples/pizza -V
0.0.1
```

如果你想让你的程序响应 `-v` 选项而不是 `-V` 选项,仅将自定义标记传递到 `version` 方法使用与 `option` 方法.

```js
program
  .version('0.0.1', '-v, --version')
```

版本旗可以命名任何东西,但需要较长的选项.

## 命令特定选项

您可以在命令中附加选项.

```js
#!/usr/bin/env node

var program = require('commander');

program
  .command('rm <dir>')
  .option('-r, --recursive', 'Remove recursively')
  .action(function (dir, cmd) {
    console.log('remove ' + dir + (cmd.recursive ? ' recursively' : ''))
  })

program.parse(process.argv)
```

在使用命令时验证命令的选项 。 任何未知的选项都会被报告为出错. 然而,如果一个基于动作的命令没有定义一个动作,那么选项就不会被验证.

## 胁迫

```js
function range(val) {
  return val.split('..').map(Number);
}

function list(val) {
  return val.split(',');
}

function collect(val, memo) {
  memo.push(val);
  return memo;
}

function increaseVerbosity(v, total) {
  return total + 1;
}

program
  .version('0.1.0')
  .usage('[options] <file ...>')
  .option('-i, --integer <n>', 'An integer argument', parseInt)
  .option('-f, --float <n>', 'A float argument', parseFloat)
  .option('-r, --range <a>..<b>', 'A range', range)
  .option('-l, --list <items>', 'A list', list)
  .option('-o, --optional [value]', 'An optional value')
  .option('-c, --collect [value]', 'A repeatable value', collect, [])
  .option('-v, --verbose', 'A value that can be increased', increaseVerbosity, 0)
  .parse(process.argv);

console.log(' int: %j', program.integer);
console.log(' float: %j', program.float);
console.log(' optional: %j', program.optional);
program.range = program.range || [];
console.log(' range: %j..%j', program.range[0], program.range[1]);
console.log(' list: %j', program.list);
console.log(' collect: %j', program.collect);
console.log(' verbosity: %j', program.verbose);
console.log(' args: %j', program.args);
```

## 正则表达式

```js
program
  .version('0.1.0')
  .option('-s --size <size>', 'Pizza size', /^(large|medium|small)$/i, 'medium')
  .option('-d --drink [drink]', 'Drink', /^(coke|pepsi|izze)$/i)
  .parse(process.argv);
  
console.log(' size: %j', program.size);
console.log(' drink: %j', program.drink);
```

## 不同论点

一个命令的最后一个论点可以是variadic的,只有最后一个论点. 为了争吵,你必须 附录 `...` 以至参数名称。 以下是一个例子:

```js
#!/usr/bin/env node

/**
 * Module dependencies.
 */

var program = require('commander');

program
  .version('0.1.0')
  .command('rmdir <dir> [otherDirs...]')
  .action(function (dir, otherDirs) {
    console.log('rmdir %s', dir);
    if (otherDirs) {
      otherDirs.forEach(function (oDir) {
        console.log('rmdir %s', oDir);
      });
    }
  });

program.parse(process.argv);
```

一个 `Array` 用于变量参数的值。 这适用于 `program.args` 和通过的论点 如上所示,您的行动.

## 指定参数语法

```js
#!/usr/bin/env node

var program = require('commander');

program
  .version('0.1.0')
  .arguments('<cmd> [env]')
  .action(function (cmd, env) {
     cmdValue = cmd;
     envValue = env;
  });

program.parse(process.argv);

if (typeof cmdValue === 'undefined') {
   console.error('no command given!');
   process.exit(1);
}
console.log('command:', cmdValue);
console.log('environment:', envValue || "no environment given");
```

尖括号(例如:. `<cmd>`) 指明所需投入。 方括号(如:. `[env]`)表示可选输入.

## Git 类子命令

```js
// file: ./examples/pm
var program = require('commander');

program
  .version('0.1.0')
  .command('install [name]', 'install one or more packages')
  .command('search [query]', 'search with optional query')
  .command('list', 'list packages installed', {isDefault: true})
  .parse(process.argv);
```

何时 `.command()` 引用时附有描述参数,否 `.action(callback)` 请求处理子命令,否则会出现错误。 这告诉指挥官,你会使用 单独的可执行文件 对于子命令,很多喜欢 `git(1)` 以及其他流行的工具.  
指挥官将尝试在条目脚本目录中搜索可执行文件( 如 `./examples/pm`名称 `program-command`一样 `pm-install`, (中文(简体) ), `pm-search`。 。 。 .

选项可以通过调用 `.command()`指定 `true` 页:1 `opts.noHelp` 将删除生成的帮助输出中的选项。 指定 `true` 页:1 `opts.isDefault` 如果没有指定其他子命令,则将运行子命令.

如果程序被设计在全球安装, 确保可执行文件有合适的模式, 如 `755`。 。 。 .

### `--harmony`

您可以启用 `--harmony` 选择的两种方式:

-   使用 `#! /usr/bin/env node --harmony` 在子命令脚本中。 请注意一些 Os 版本不支持此模式 .
-   使用 `--harmony` 选项,例如 `node --harmony examples/pm publish`编辑 `--harmony` 选项将在生成子命令进程时保存.

## 自动 -- 帮助

帮助信息是自动生成的,基于信息指挥官已经知道您的程序,所以如下 `--help` 信息是免费的:

```
 $ ./examples/pizza --help

   Usage: pizza [options]

   An application for pizzas ordering

   Options:

     -h, --help           output usage information
     -V, --version        output the version number
     -p, --peppers        Add peppers
     -P, --pineapple      Add pineapple
     -b, --bbq            Add bbq sauce
     -c, --cheese <type>  Add the specified type of cheese [marble]
     -C, --no-cheese      You do not want any cheese

```

## 自定义帮助

您可以显示任意 `-h, --help` 资料 -帮助。 指挥官会自动 完成后退出, 以便完成剩余程序 不执行导致不受欢迎的行为,例如 在以下可执行文件“ stuff”中,当 `--help` 已使用.

```js
#!/usr/bin/env node

/**
 * Module dependencies.
 */

var program = require('commander');

program
  .version('0.1.0')
  .option('-f, --foo', 'enable some foo')
  .option('-b, --bar', 'enable some bar')
  .option('-B, --baz', 'enable some baz');

// must be before .parse() since
// node's emit() is immediate

program.on('--help', function(){
  console.log('  Examples:');
  console.log('');
  console.log('    $ custom-help --help');
  console.log('    $ custom-help -h');
  console.log('');
});

program.parse(process.argv);

console.log('stuff');
```

使用下列帮助输出时 `node script-name.js -h` 或者说 `node script-name.js --help` 运行中 :

```

Usage: custom-help [options]

Options:

  -h, --help     output usage information
  -V, --version  output the version number
  -f, --foo      enable some foo
  -b, --bar      enable some bar
  -B, --baz      enable some baz

Examples:

  $ custom-help --help
  $ custom-help -h

```

## 输出帮助( cb)

输出帮助信息而不退出. 可选的回调cb允许在显示前对帮助文本进行后处理.

如果您想要默认显示帮助( 如未提供命令), 您可以使用诸如 :

```js
var program = require('commander');
var colors = require('colors');

program
  .version('0.1.0')
  .command('getstream [url]', 'get stream URL')
  .parse(process.argv);

if (!process.argv.slice(2).length) {
  program.outputHelp(make_red);
}

function make_red(txt) {
  return colors.red(txt); //display the help text in red on the console
}
```

## 帮助(cb)

输出帮助信息并立即退出. 可选的回调cb允许在显示前对帮助文本进行后处理.

## 实例

```js
var program = require('commander');

program
  .version('0.1.0')
  .option('-C, --chdir <path>', 'change the working directory')
  .option('-c, --config <path>', 'set config path. defaults to ./deploy.conf')
  .option('-T, --no-tests', 'ignore test hook');

program
  .command('setup [env]')
  .description('run setup commands for all envs')
  .option("-s, --setup_mode [mode]", "Which setup mode to use")
  .action(function(env, options){
    var mode = options.setup_mode || "normal";
    env = env || 'all';
    console.log('setup for %s env(s) with %s mode', env, mode);
  });

program
  .command('exec <cmd>')
  .alias('ex')
  .description('execute the given remote cmd')
  .option("-e, --exec_mode <mode>", "Which exec mode to use")
  .action(function(cmd, options){
    console.log('exec "%s" using %s mode', cmd, options.exec_mode);
  }).on('--help', function() {
    console.log('  Examples:');
    console.log();
    console.log('    $ deploy exec sequential');
    console.log('    $ deploy exec async');
    console.log();
  });

program
  .command('*')
  .action(function(env){
    console.log('deploying "%s"', env);
  });

program.parse(process.argv);
```

更多演示词可见于 [实例](https://github.com/tj/commander.js/tree/master/examples) 目录.

## 许可证

麻省理工学院

## 常见问题

### @gemini-testing/commander 是什么？

用于节点\.js命令行程序的完整解决方案

### 如何安装 @gemini-testing/commander？

在项目目录运行 npm install @gemini-testing/commander，或使用 pnpm add / yarn add / bun add。

### @gemini-testing/commander 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @gemini-testing/commander 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @gemini-testing/commander 可以商用吗？

@gemini-testing/commander 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @gemini-testing/commander 的下载量有多少？

根据 npm 官方下载统计，@gemini-testing/commander 在 2026/10/16 – 2026/11/14 这 30 天内被下载 20,432 次，日均约 681 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @gemini-testing/commander 还在维护吗？

最新版本 2\.15\.4 发布于 2024/08/09（2 年前）；至今共发布 4 个版本，其中过去 12 个月发布了 0 个；首次发布于 2018/07/31。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。

