完全指南：必选、可选与spread参数定义清单及8个常见坑)
cleye参数(parameters)完全指南：必选、可选与spread参数定义清单及8个常见坑
【免费下载链接】cleye👁🗨 Strongly typed CLI development for Node.js项目地址: https://gitcode.com/gh_mirrors/cl/cleye
cleye 是 Node.js 生态中一款轻量、强类型的命令行（CLI）开发工具，负责解析命令行输入并自动生成--help文档。本文带你完整理解cleye 参数（parameters）的用法：必选参数、可选参数、spread 参数的定义规则、命名转换，以及 8 个新手最常踩的坑。
一、cleye 参数与 flags 的区别
在 cleye 中，命令行输入分两类：
- 参数（parameters，又称位置参数）：不带
--前缀的值，如node my-script a.txt b.txt中的a.txt、b.txt - 标志（flags）：键值对形式，如
--output dist
把参数定义在parameters数组中后，cleye 会自动完成三件事：命名访问（按名字取值而非下标）、必选校验（缺失即报错退出）、帮助文档生成。
二、4 种参数定义语法速查表
cleye 支持 4 种参数写法，这是使用 cleye 参数时最核心的清单：
| 写法 | 含义 | 取值类型 |
|---|---|---|
<package name> | 必选参数 | string |
[output] | 可选参数 | string \| undefined |
<files...> | 必选 spread 参数（≥1 个） | string[] |
[rest...] | 可选 spread 参数（≥0 个） | string[] |
一个典型示例：
import { cli } from 'cleye' const argv = cli({ name: 'my-script', parameters: [ '<input file>', // 必选 '[output file]', // 可选 '[extra files...]' // spread，吃掉剩余全部 ] }) // $ node my-script a.txt b.txt c.txt d.txt argv._.inputFile // "a.txt" argv._.outputFile // "b.txt" argv._.extraFiles // ["c.txt", "d.txt"]TypeScript 下，cleye 会根据 4 种写法精确推断每个参数的类型，编辑器提示非常清晰：
类型映射逻辑见 src/types.ts 中的ParameterType，运行时解析在 src/cli.ts 的parseParameters函数中。
三、参数名如何变成属性名（camelCase 转换规则）
参数名支持多词，访问时统一转换为 camelCase 挂在argv._上：
<first name>→argv._.firstName<file-path>/<file_path>/<file path>→ 同样得到filePath<value1>→argv._.value1（数字原样保留）
⚠️ 三个容易踩的转换细节（均出自 tests/specs/edge-cases.ts）：
- 名称以
-、_、空格开头时，首字母会被大写：<-value>→argv._.Value - 名称本身含大写字母时不做任何改动：
<FileNAME>→argv._.FileNAME - 以数字开头的名称只能用括号访问：
<1value>→argv._['1value']
转换规则实现于 src/utils/convert-case.ts。
四、spread 参数与--结束符
spread 参数（...后缀）会消费它之后剩余的全部参数值，适合"接收任意多个文件"这类场景。
--（end-of-flags）是 cleye 参数中的特殊分隔符，用于把"自己的参数"和"透传给子进程的参数"分开，例如npm run <script> -- <script arguments>中--后的内容属于脚本本身：
const argv = cli({ name: 'npm-run', parameters: ['<script>', '--', '[arguments...]'] }) // $ npm-run echo -- hello world argv._.script // "echo" argv._.arguments // ["hello", "world"]关键规则：--会把参数列表切分为两段独立校验——--前的参数只消费--之前的值，--后的参数只消费--之后的值（见 src/cli.ts 中hasEof处理逻辑）。没有--后的值时，可选的--段参数保持undefined，不会报错。
五、参数自动生成帮助文档
你写的每个参数都会自动出现在--help的 Usage 行中，必选/可选语义一目了然（<pkg-path>为必选参数）：
如果你的 CLI 包含多个命令（command），每个命令可单独定义自己的 parameters，类型会自动按命令收窄：
六、cleye 参数的 8 个常见坑 🕳️
以下 8 个坑全部来自 src/cli.ts 的真实校验逻辑与 tests/specs/arguments.ts 的测试用例：
坑 1：忘记用尖括号或方括号包裹
parameters: ['value-a']直接抛出：
Invalid parameter: "value-a". Must be wrapped in <> (required parameter) or [] (optional parameter)坑 2：参数名包含特殊字符
.、|、\、{}、()、^、$、+、*、?都不允许，例如[value.a]会报Invalid character found "."。放心使用的是连字符-、下划线_、空格和数字。
坑 3：必选参数放在可选参数之后
['[value-a]', '<value-b>']会报错：必选参数<value-b>不能出现在可选参数之后——否则用户省略可选值时，必选值将无法对齐。
坑 4：spread 参数没放在最后
['[value-a...]', '<value-b>']会报Spread parameter "[value-a...]" must be last。多个 spread 同样不允许，spread 只能有一个且必须殿后。
坑 5：参数名重复（含跨--段）
['[value-a]', '[value-a]']报is used more than once。注意：--前后使用同名参数也会被判为重复，因为最终都挂在同一个argv._上。
坑 6：写了两个--分隔符
只有第一个--会被识别为结束符，第二个--会被当作普通参数解析，从而抛出"必须用<>或[]包裹"的报错。
坑 7：按原始参数名访问属性
<first name>要访问argv._.firstName，而不是argv._['first name']。忽略 camelCase 转换（见第三节）是"参数明明解析了却取到undefined"的最常见原因。
坑 8：以为缺失必选参数会抛出可捕获异常
缺失必选参数（含必选 spread 为 0 个、--段必选参数缺失）时，cleye 的行为是：打印Error: Missing required parameter "xxx"→ 自动输出帮助文档 →process.exit(1)直接退出进程，不会throw，因此无法在调用方try/catch捕获。
七、获取与延伸阅读
安装：
npm i cleye克隆源码仓库：
git clone https://gitcode.com/gh_mirrors/cl/cleye推荐阅读路径：
- 入门示例：
examples/greet/index.ts（必选 + 可选参数） - 多命令示例：
examples/npm/commands/install.ts、examples/tsc/index.ts - 参数校验测试：
tests/specs/arguments.ts、tests/specs/edge-cases.ts - 类型定义：
src/types.ts
掌握"4 种写法 + 顺序规则 + camelCase 转换"这三点，你就能避开上面全部 8 个坑，写出带自动校验和--help文档的 Node.js 命令行脚本。
【免费下载链接】cleye👁🗨 Strongly typed CLI development for Node.js项目地址: https://gitcode.com/gh_mirrors/cl/cleye
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
