# 1. 安裝 Node.js (建議 LTS 版)
# 2. 安裝 Yeoman 脚手架工具
npm install -g yo
# 3. 安裝 CLI 專案生成器
npm install -g generator-cli-starter
# 互動式建立專案
yo cli-starter
# 提示輸入:
# ? Project name: my-cli
# ? Command name: mycmd
# ? Description: My awesome CLI tool
# ? Author: Your Name
# ? License: MIT
my-cli/
├── bin/
│ └── mycmd.js # 入口檔 (shebang + commander 設定)
├── lib/
│ └── index.js # 核心邏輯
├── test/
│ └── index.test.js # 單元測試
├── package.json # 專案設定
└── README.md
#!/usr/bin/env node
'use strict';
const program = require('commander');
const pkg = require('../package.json');
const { processFiles } = require('../lib');
program
.name('mycmd')
.description('My awesome CLI tool')
.version(pkg.version);
// 主命令
program
.command('process [output]')
.description('處理輸入檔案')
.option('-r, --recursive', '遞迴處理目錄')
.option('-e, --ext ', '指定副檔名', ['.js', '.ts'])
.option('-j, --jobs ', '平行處理數', 4, parseInt)
.action(async (input, output, options) => {
try {
await processFiles(input, output, options);
console.log('✅ 處理完成');
} catch (err) {
console.error('❌ 失敗:', err.message);
process.exit(1);
}
});
// 子命令範例
program
.command('config [value]')
.description('管理設定')
.action((key, value) => {
if (value === undefined) {
console.log(`config.${key} = ${getConfig(key)}`);
} else {
setConfig(key, value);
console.log(`已設定 ${key} = ${value}`);
}
});
program.parse(process.argv);
// 若無參數顯示幫助
if (!process.argv.slice(2).length) {
program.outputHelp();
}
const fs = require('fs').promises;
const path = require('path');
const { Worker } = require('worker_threads');
async function processFiles(input, output, options) {
const { recursive, ext, jobs } = options;
// 1. 收集檔案
const files = await collectFiles(input, recursive, ext);
console.log(`找到 ${files.length} 個檔案`);
// 2. 平行處理 (Worker Threads)
const results = await parallelProcess(files, jobs, async (file) => {
const content = await fs.readFile(file, 'utf8');
// 實際處理邏輯...
const processed = content.toUpperCase(); // 範例:轉大寫
if (output) {
const relPath = path.relative(input, file);
const outPath = path.join(output, relPath);
await fs.mkdir(path.dirname(outPath), { recursive: true });
await fs.writeFile(outPath, processed);
}
return { file, size: processed.length };
});
// 3. 輸出摘要
const totalSize = results.reduce((sum, r) => sum + r.size, 0);
console.log(`總計處理 ${results.length} 檔案,${totalSize} 字元`);
}
async function collectFiles(dir, recursive, extensions) {
const entries = await fs.readdir(dir, { withFileTypes: true });
const files = [];
for (const entry of entries) {
const fullPath = path.join(dir, entry.name);
if (entry.isDirectory()) {
if (recursive) {
files.push(...await collectFiles(fullPath, recursive, extensions));
}
} else if (extensions.some(ext => entry.name.endsWith(ext))) {
files.push(fullPath);
}
}
return files;
}
async function parallelProcess(items, concurrency, processor) {
const results = [];
const queue = [...items];
const workers = [];
async function worker() {
while (queue.length) {
const item = queue.shift();
try {
results.push(await processor(item));
} catch (err) {
results.push({ error: err.message, item });
}
}
}
for (let i = 0; i < Math.min(concurrency, items.length); i++) {
workers.push(worker());
}
await Promise.all(workers);
return results;
}
module.exports = { processFiles };
# 1. 登入 npm
npm login
# 2. 確認 package.json 關鍵欄位
{
"name": "my-cli",
"version": "1.0.0",
"bin": { "mycmd": "./bin/mycmd.js" }, // 關鍵:定義指令名稱
"files": ["bin", "lib"], // 發布包含的目錄
"preferGlobal": true // 建議全域安裝
}
# 3. 發布
npm publish
# 4. 使用者安裝
npm install -g my-cli
mycmd --help
| 功能 | 套件 | 用途 |
|---|---|---|
| 彩色輸出 | chalk | console.log(chalk.green('成功')) |
| 進度條 | cli-progress | 長時間任務視覺化 |
| 互動式提示 | inquirer | 選單、確認、輸入驗證 |
| 配置管理 | cosmiconfig | 多來源配置 (.rc, package.json, env) |
| 自動更新提醒 | update-notifier | 檢查新版本並通知 |
| TypeScript 支援 | ts-node, @types/node | 型別安全開發 |
// test/index.test.js
const { processFiles } = require('../lib');
const fs = require('fs').promises;
const path = require('path');
const tmp = require('tmp-promise');
test('processFiles 基本功能', async () => {
const { path: tmpDir, cleanup } = await tmp.dir();
const input = path.join(tmpDir, 'in');
const output = path.join(tmpDir, 'out');
await fs.mkdir(input);
await fs.writeFile(path.join(input, 'a.txt'), 'hello');
await processFiles(input, output, { recursive: false, ext: ['.txt'], jobs: 1 });
const result = await fs.readFile(path.join(output, 'a.txt'), 'utf8');
expect(result).toBe('HELLO');
await cleanup();
});
掌握此流程,即可快速建構專業級、可發布、可維護的 Node.js CLI 工具。