萬盛學電腦網

您现在的位置: 萬盛學電腦網 >> 程式設計 >  >> 腳本程式專題 >> JavaScript

Node.js 命令行參數解析利器:Commander.js 完整使用指南

為什麼需要 Commander.js?

Node 內建 process.argv 只提供原始參數陣列,解析極其麻煩。Commander.js(由 TJ Holowaychuk 編寫)提供聲明式 API,自動生成幫助信息,支援子命令、選項驗證、類型轉換等,是構建 CLI 工具的首選。

安裝

npm install commander

基礎用法:選項定義與解析

#!/usr/bin/env node
const { program } = require('commander');

program
  .version('0.0.1')
  .option('-p, --peppers', '添加辣椒')
  .option('-P, --pineapple', '添加鳳梨')
  .option('-b, --bbq', '添加 BBQ 醬')
  .option('-c, --cheese [type]', '添加指定起司 [預設: marble]', 'marble')
  .parse(process.argv);

console.log('你點的披薩包含:');
if (program.peppers) console.log(' - 辣椒');
if (program.pineapple) console.log(' - 鳳梨');
if (program.bbq) console.log(' - BBQ 醬');
console.log(' - %s 起司', program.cheese);

執行測試:

$ node pizza.js -p -P -c cheddar
你點的披薩包含:
 - 辣椒
 - 鳳梨
 - cheddar 起司

進階功能

1. 自動生成 --help

無需額外代碼,直接運行 node pizza.js --help 即可看到格式化幫助:

Usage: pizza [options]

Options:
  -V, --version        output the version number
  -p, --peppers        添加辣椒
  -P, --pineapple      添加鳳梨
  -b, --bbq            添加 BBQ 醬
  -c, --cheese [type]  添加指定起司 [預設: marble]
  -h, --help           output usage information

2. 自定義幫助內容

program.on('--help', () => {
  console.log('');
  console.log('範例:');
  console.log('  $ pizza -p -P          # 加辣椒和鳳梨');
  console.log('  $ pizza --cheese=mozzarella # 指定馬茲瑞拉起司');
  console.log('');
});

3. 參數類型轉換與驗證

function range(val) {
  return val.split('..').map(Number); // '1..5' -> [1,5]
}
function list(val) {
  return val.split(','); // 'a,b,c' -> ['a','b','c']
}
function collect(val, memo) {
  memo.push(val);
  return memo; // 可重複選項累積
}

program
  .option('-r, --range ..', '數字範圍', range)
  .option('-l, --list ', '逗號分隔列表', list)
  .option('-o, --optional [value]', '可選值')
  .option('-c, --collect [value]', '可重複收集', collect, []);

4. 子命令

program
  .command('deploy ')
  .description('部署到指定環境')
  .action((env) => {
    console.log('Deploying to %s...', env);
  });

program.parse(process.argv);

完整範例:功能豐富的 CLI 工具

#!/usr/bin/env node
const { program } = require('commander');

program
  .version('1.0.0')
  .name('my-tool')
  .usage('[options] ')
  .option('-v, --verbose', '詳細輸出')
  .option('-c, --config ', '配置文件路徑');

program
  .command('build')
  .description('構建專案')
  .option('--prod', '生產模式')
  .action((options) => {
    console.log('Building...', options.prod ? '(production)' : '(development)');
  });

program
  .command('serve')
  .description('啟動開發伺服器')
  .option('-p, --port ', '端口號', '3000')
  .action((options) => {
    console.log('Server running on port', options.port);
  });

program.parse(process.argv);

// 無子命令時顯示幫助
if (!process.argv.slice(2).length) {
  program.outputHelp();
}

最佳實踐建議

  • 在 package.json 的 bin 欄位註冊入口,發布後可直接全域執行命令。
  • 善用 program.opts() 獲取所有選項物件,避免屬性名衝突。
  • 組合使用 requiredOption() 強制必填參數。
  • 子命令獨立文件管理,主入口僅註冊,保持代碼清晰。
copyright © 萬盛學電腦網 all rights reserved