Node.js脚本需以#!/usr/bin/env node开头才能作为命令行工具运行，否则会被shell错误解析；process.argv[2]起为用户参数，需手动解析短选项合并、等号/空格两种写法。
Node.js 脚本必须加 #!/usr/bin/env node 才能当命令行工具用
不加这行，系统会默认用 shell 解释你的 JS 文件，直接报错 ReferenceError: require is not defined 或 command not found。它不是可选注释，而是告诉操作系统“用 node 运行这个文件”。
实操建议：
- 把
#!/usr/bin/env node放在文件第一行（前面不能有任何空格或 BOM） - 保存为无扩展名文件（如
mycli），然后chmod +x mycli - 全局使用需软链：
sudo ln -s $(pwd)/mycli /usr/local/bin/mycli，或通过npm link注册 - Windows 用户注意：该 shebang 在 cmd/PowerShell 里被忽略，但 WSL 和 npm scripts 下仍需保留以保跨平台一致性
process.argv 是最轻量的参数获取方式，但得手动切数组
process.argv 返回的是完整命令行参数数组，前两个固定是 node 可执行路径和脚本路径，真正参数从索引 2 开始。比如运行 mycli --input data.json -v，process.argv 是 ['/path/to/node', '/path/to/mycli', '--input', 'data.json', '-v']。
常见错误现象：
立即学习“Java免费学习笔记（深入）”；
- 误用
process.argv[0]或[1]拿用户参数 → 得到的是路径，不是值 - 没处理短选项合并（
-abc应拆成-a -b -c），导致解析失败 - 没考虑等号写法（
--file=path.txt）和空格写法（--file path.txt）混用
简单健壮做法：
const args = process.argv.slice(2);
let input = '';
let verbose = false;
for (let i = 0; i < args.length; i++) {
if (args[i] === '--input' && args[i + 1]) {
input = args[i + 1];
i++;
} else if (args[i] === '-v' || args[i] === '--verbose') {
verbose = true;
} else if (args[i].startsWith('--input=')) {
input = args[i].split('=', 2)[1];
}
}
用 minimist 替代手写解析，5 行代码搞定基础需求
minimist 是零依赖、无副作用的参数解析库，适合小工具。它不处理 help 提示或类型校验，但能把 ['--port', '3000', '-d', './src'] 直接转成 { port: 3000, d: './src' }，自动转换数字、布尔、数组。
使用场景：
- 你只需要快速支持
--flag、-f、--name=value、位置参数 - 不想引入
yargs那种带 CLI 自动渲染的重型方案 - 构建 CI 脚本、本地 dev 工具、一次性迁移命令
安装与基本用法：
npm install minimist
const argv = require('minimist')(process.argv.slice(2));
console.log(argv.port); // 3000
console.log(argv._); // ['file1.js', 'file2.js'] ← 位置参数
注意点：
-
minimist不支持-abc这种连写短选项（会当成一个字符串键'abc'），要支持得自己预处理或换commander - 它不会抛错，非法输入静默忽略，所以关键参数建议手动检查：
if (!argv.input) throw new Error('missing --input')
错误退出码和标准流输出决定工具是否“可集成”
命令行工具被其他脚本调用时（比如 shell 的 &&、CI 的 step），只看 process.exitCode 和 stdout/stderr。返回 0 表示成功，非 0（通常是 1）表示失败 —— 即使你打印了 “Done!”，只要 exitCode ≠ 0，上游就认为出错了。
实操要点：
- 所有错误必须写到
process.stderr，别用console.log（它默认走 stdout） - 显式设置
process.exitCode = 1，或直接process.exit(1)（后者会立即终止） - 不要在异步操作完成前就退出，比如忘记
await一个 Promise 就 return → 导致 exitCode 被设为 0，但实际任务失败 - 输出结构化数据（如 JSON）时，确保只输出一次且无额外空行或提示文字，否则下游
jq解析失败
示例：
async function run() {
try {
const result = await doSomething();
console.log(JSON.stringify(result)); // stdout，给机器读
} catch (err) {
process.stderr.write(`Error: ${err.message}\n`); // stderr，给人看
process.exitCode = 1;
}
}
run();
最容易被忽略的是异步错误边界和 stderr/stdout 混用——很多工具本地跑得通，一进 CI 就卡住或误判状态，根源往往在这里。
