1. 从零搭建 TypeScript CLI 时我踩过的那些坑如果你正在用 Node.js 写命令行工具大概率会遇到这几个问题参数解析靠process.argv手撕、子命令越加越乱、类型提示全靠脑补、--help输出丑得没法看。我最初写第一个 CLI 工具时就是用一个switch (argv[2])硬扛结果加到第五个子命令时代码已经没法维护了。Commander 是目前 Node.js 生态里最成熟的命令行框架之一配合commander-js/extra-typings这个类型增强库可以在 TypeScript 下获得完整的类型推导——包括.action()回调里参数和选项的类型都能自动推断出来。这意味着你写program.option(--port number)之后在 action 里拿到的options.port会被推导成string | undefined而不是any。这篇文章面向的是想用 TypeScript 搭建可扩展 CLI 骨架的开发者。我会从工程目录结构开始一步步拆解子命令注册、参数解析、命令分发、错误处理最后给出本地运行验证的完整步骤。整套代码可以直接复制到你的项目里跑起来。核心检索词就是Commander 子命令 TypeScript 参数解析你跟着做就能得到一个能用的 CLI 骨架。我试过用 yargs、oclif、cac 这些方案最后回到 Commander 的原因很简单它的 API 设计足够克制类型支持在 extra-typings 加持下几乎完美而且社区体量决定了你遇到问题基本都能搜到答案。下面进入正题。2. 前置准备TaoToken 接入与工程初始化在开始写 CLI 之前先把运行环境和一个可用的模型调用通道准备好。CLI 工具很多时候需要调用大模型能力比如代码生成、文本处理所以我会把 TaoToken 的接入也一并配置好这样你的 CLI 骨架搭完之后可以直接接上模型调用。TaoToken 是一个面向开发者的模型调用平台提供 OpenAI 兼容的 API 接口。官网地址是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 端点是 https://taotoken.net/api 。它的作用是让你在 CLI 工具里通过统一的 Base URL 和 API Key 调用多种模型不需要为每个模型单独适配 SDK。2.1 工程目录结构先建目录。我推荐的 CLI 工程结构是这样的my-cli/ ├── src/ │ ├── index.ts # 入口注册 program │ ├── commands/ │ │ ├── index.ts # 命令聚合导出 │ │ ├── greet.ts # greet 子命令 │ │ ├── config.ts # config 子命令含 set/get/list │ │ └── ask.ts # ask 子命令调用模型 │ ├── lib/ │ │ ├── client.ts # TaoToken 客户端封装 │ │ └── config-store.ts # 本地配置读写 │ └── utils/ │ └── logger.ts # 日志工具 ├── package.json ├── tsconfig.json └── .env这个结构的核心思路是index.ts只负责组装 program每个子命令独立一个文件业务逻辑放在lib/里。这样加新命令时只需要新建一个文件然后在commands/index.ts里注册一下。2.2 依赖安装与 tsconfig 配置初始化项目并安装依赖mkdir my-cli cd my-cli npm init -y npm install commander commander-js/extra-typings dotenv npm install -D typescript tsx types/nodetsx用来在开发时直接运行 TypeScript不用先编译。tsconfig.json配置如下{ compilerOptions: { target: ES2022, module: NodeNext, moduleResolution: NodeNext, outDir: dist, rootDir: src, strict: true, esModuleInterop: true, skipLibCheck: true, resolveJsonModule: true, declaration: true }, include: [src/**/*] }package.json里加上bin字段和脚本{ name: my-cli, version: 0.1.0, type: module, bin: { mycli: ./dist/index.js }, scripts: { dev: tsx src/index.ts, build: tsc, start: node dist/index.js } }注意type: module这一行它决定了你的 import 路径需要带.js后缀NodeNext 模式。这是很多人第一次配 TypeScript CLI 时踩的坑后面排障章节会详细说。2.3 TaoToken 环境变量配置在项目根目录建一个.env文件TAOTOKEN_API_KEYsk-your-key-here TAOTOKEN_BASE_URLhttps://taotoken.net/api TAOTOKEN_MODELclaude-sonnet-4-5-20250929API Key 可以在 https://taotoken.net/api-keys 这个地址生成。注意 Base URL 不要带末尾斜杠SDK 内部会自己拼接/v1/chat/completions这类路径。模型 ID 根据你实际要用的模型填这里只是示例。3. 可复制配置Commander 子命令与参数解析完整实现这一节是全文的核心我会把每个文件的完整代码贴出来你直接复制就能跑。3.1 入口文件 index.ts#!/usr/bin/env node import { Command } from commander-js/extra-typings; import { registerCommands } from ./commands/index.js; import { loadEnv } from ./lib/config-store.js; loadEnv(); const program new Command() .name(mycli) .description(一个用 Commander TypeScript 搭建的 CLI 骨架) .version(0.1.0, -v, --version, 输出当前版本号) .helpOption(-h, --help, 显示帮助信息) .configureHelp({ sortSubcommands: true, sortOptions: true, }); registerCommands(program); program.parseAsync(process.argv).catch((err) { console.error([mycli] 执行失败:, err instanceof Error ? err.message : err); process.exit(1); });这里有几个关键点。第一行#!/usr/bin/env node是 shebang编译后 npm link 才能直接执行。.configureHelp({ sortSubcommands: true, sortOptions: true })让帮助输出按字母排序命令多了之后体验会好很多。parseAsync而不是parse因为我们的 action 回调里有异步操作比如调用模型 API。3.2 命令聚合 commands/index.tsimport type { Command } from commander-js/extra-typings; import { registerGreetCommand } from ./greet.js; import { registerConfigCommand } from ./config.js; import { registerAskCommand } from ./ask.js; export function registerCommands(program: Command) { registerGreetCommand(program); registerConfigCommand(program); registerAskCommand(program); }这个文件就是命令注册的总入口。每加一个新命令import 一行、调用一行非常清晰。3.3 greet 子命令最简参数解析示例import { Command } from commander-js/extra-typings; export function registerGreetCommand(program: Command) { program .command(greet) .description(向指定用户打招呼) .argument(name, 要打招呼的名字) .option(-u, --uppercase, 输出大写, false) .option(-r, --repeat times, 重复次数, 1) .action((name, options) { const times Number.parseInt(options.repeat, 10); if (Number.isNaN(times) || times 1) { throw new Error(--repeat 必须是大于 0 的整数); } const msg Hello, ${name}!; const output options.uppercase ? msg.toUpperCase() : msg; for (let i 0; i times; i) { console.log(output); } }); }注意.argument(name)里的尖括号表示必填参数方括号[name]表示可选。.option(-r, --repeat times, 重复次数, 1)第三个参数是默认值。在 action 回调里name和options的类型都是自动推导的——options.uppercase是booleanoptions.repeat是string。这就是 extra-typings 的价值。3.4 config 子命令嵌套子命令与配置读写import { Command } from commander-js/extra-typings; import { readConfig, writeConfig } from ../lib/config-store.js; export function registerConfigCommand(program: Command) { const config program .command(config) .description(管理本地配置); config .command(set) .description(设置配置项) .argument(key, 配置键) .argument(value, 配置值) .action((key, value) { const cfg readConfig(); cfg[key] value; writeConfig(cfg); console.log(已设置 ${key} ${value}); }); config .command(get) .description(读取配置项) .argument(key, 配置键) .action((key) { const cfg readConfig(); if (!(key in cfg)) { console.error(配置项 ${key} 不存在); process.exit(1); } console.log(cfg[key]); }); config .command(list) .description(列出所有配置) .option(--json, 以 JSON 格式输出, false) .action((options) { const cfg readConfig(); if (options.json) { console.log(JSON.stringify(cfg, null, 2)); } else { for (const [k, v] of Object.entries(cfg)) { console.log(${k} ${v}); } } }); }嵌套子命令的写法就是先创建父命令config然后在它上面继续.command(set)。这样mycli config set foo bar就能正确路由到对应的 action。3.5 ask 子命令接入 TaoToken 模型调用import { Command } from commander-js/extra-typings; import { chatCompletion } from ../lib/client.js; export function registerAskCommand(program: Command) { program .command(ask) .description(向模型提问) .argument(prompt, 你的问题) .option(-m, --model model, 指定模型 ID) .option(-s, --stream, 流式输出, false) .action(async (prompt, options) { const model options.model ?? process.env.TAOTOKEN_MODEL; if (!model) { throw new Error(未指定模型请用 --model 或设置 TAOTOKEN_MODEL); } const answer await chatCompletion({ model, messages: [{ role: user, content: prompt }], stream: options.stream, }); console.log(answer); }); }3.6 TaoToken 客户端封装 lib/client.tsinterface ChatParams { model: string; messages: Array{ role: string; content: string }; stream?: boolean; } export async function chatCompletion(params: ChatParams): Promisestring { const apiKey process.env.TAOTOKEN_API_KEY; const baseUrl process.env.TAOTOKEN_BASE_URL ?? https://taotoken.net/api; if (!apiKey) { throw new Error(缺少 TAOTOKEN_API_KEY请在 .env 中配置); } const res await fetch(${baseUrl}/v1/chat/completions, { method: POST, headers: { Content-Type: application/json, Authorization: Bearer ${apiKey}, }, body: JSON.stringify({ model: params.model, messages: params.messages, stream: false, }), }); if (!res.ok) { const text await res.text(); throw new Error(请求失败 ${res.status}: ${text}); } const data (await res.json()) as { choices: Array{ message: { content: string } }; }; return data.choices[0]?.message?.content ?? ; }这里用的是原生fetchNode 18 内置没有引入额外 SDK保持依赖最小。Base URL 从环境变量读取默认值就是 TaoToken 的 API 地址。3.7 配置存储 lib/config-store.tsimport { readFileSync, writeFileSync, existsSync, mkdirSync } from node:fs; import { homedir } from node:os; import { join } from node:path; import { config as loadDotenv } from dotenv; const CONFIG_DIR join(homedir(), .mycli); const CONFIG_FILE join(CONFIG_DIR, config.json); export function loadEnv() { loadDotenv(); } export function readConfig(): Recordstring, string { if (!existsSync(CONFIG_FILE)) return {}; try { return JSON.parse(readFileSync(CONFIG_FILE, utf8)); } catch { return {}; } } export function writeConfig(cfg: Recordstring, string) { if (!existsSync(CONFIG_DIR)) { mkdirSync(CONFIG_DIR, { recursive: true }); } writeFileSync(CONFIG_FILE, JSON.stringify(cfg, null, 2), utf8); }配置文件放在用户主目录的.mycli/config.json这是 CLI 工具的通用做法避免污染项目目录。4. 验证请求本地运行与成功结果确认代码写完了现在来验证。整个过程分三步编译检查、本地运行、模型调用测试。4.1 类型检查与编译先跑一遍 TypeScript 编译确认没有类型错误npx tsc --noEmit如果没有输出说明类型全部通过。这一步很重要因为 Commander 的类型推导有时候会因为参数顺序写错而报错早发现早修。然后正式编译npm run build编译产物在dist/目录下。你可以用node dist/index.js --help看看输出。4.2 用 tsx 直接运行开发版本开发阶段不用每次编译直接用 tsx 跑npm run dev -- --help预期输出Usage: mycli [options] [command] 一个用 Commander TypeScript 搭建的 CLI 骨架 Options: -v, --version 输出当前版本号 -h, --help 显示帮助信息 Commands: ask 向模型提问 config 管理本地配置 greet 向指定用户打招呼 help 显示命令帮助注意命令是按字母排序的这是sortSubcommands: true的效果。4.3 测试 greet 子命令npm run dev -- greet World --uppercase --repeat 3预期输出HELLO, WORLD! HELLO, WORLD! HELLO, WORLD!再测试参数校验npm run dev -- greet World --repeat abc预期输出错误[mycli] 执行失败: --repeat 必须是大于 0 的整数4.4 测试 config 子命令npm run dev -- config set theme dark npm run dev -- config get theme npm run dev -- config list --json预期输出分别是已设置 theme dark、dark、以及格式化后的 JSON。配置文件会写到~/.mycli/config.json。4.5 测试 ask 子命令调用模型确保.env里配好了TAOTOKEN_API_KEY然后npm run dev -- ask 用一句话解释什么是 CLI --model claude-sonnet-4-5-20250929如果一切正常你会看到模型返回的一句话解释。这一步验证了从 CLI 参数解析到 HTTP 请求再到结果输出的完整链路。4.6 npm link 全局测试想让mycli命令全局可用npm run build npm link mycli greet TaoTokennpm link会把dist/index.js软链到全局 bin 目录。测试完可以用npm unlink -g my-cli取消。5. 本篇常见错误排查401、local proxy failed 与类型报错这一节整理我在搭建过程中真实遇到过的报错以及对应的排查思路。5.1 401 Unauthorized调用ask命令时如果返回请求失败 401: {error:{message:Invalid API key}}排查顺序第一确认.env文件在项目根目录且loadEnv()在index.ts顶部被调用第二确认TAOTOKEN_API_KEY的值没有多余空格或引号第三确认 Key 没有过期可以到 https://taotoken.net/api-keys 重新生成一个。注意.env不会被自动加载必须显式调用dotenv.config()我在loadEnv()里做了这件事。5.2 local proxy failed 类网络错误如果看到类似fetch failed或连接超时的报错先确认TAOTOKEN_BASE_URL的值是否正确。常见错误是末尾多了一个斜杠导致拼接出https://taotoken.net/api//v1/chat/completions这种双斜杠路径。正确写法是https://taotoken.net/api不带末尾斜杠。另外确认你的网络能正常访问该域名可以用curl https://taotoken.net/api/v1/models -H Authorization: Bearer $TAOTOKEN_API_KEY单独测试连通性。5.3 reading choices of undefined这个报错说明响应体结构和预期不符。通常是两种情况一是 API 返回了错误对象而不是正常的 completion 结构但你的代码直接去读data.choices[0]二是模型 ID 写错了服务端返回了错误信息。修复方式是在chatCompletion里先判断res.ok不 ok 就抛出带状态码的错误我在 3.6 的代码里已经这么做了。如果你拿到的是流式响应但按非流式解析也会出现这个问题确认stream: false。5.4 ERR_MODULE_NOT_FOUND 与 .js 后缀这是 NodeNext 模式下最常见的坑。报错长这样Error [ERR_MODULE_NOT_FOUND]: Cannot find module /path/src/commands/greet原因是你 import 时写的是./commands/greet但 NodeNext 要求 ESM 的相对导入必须带扩展名。修复方式是把所有相对导入改成./commands/greet.js——注意即使源文件是.ts导入路径也要写.js因为编译后是.js。这个规则第一次接触会很别扭但习惯了就好。5.5 Commander 类型推导失败如果你写.action((name, options) {...})时options被推导成any或报类型错误检查两点一是确认 import 的是commander-js/extra-typings而不是commander二是确认.option()的调用顺序在.action()之前。extra-typings 的类型是通过链式调用累积推导的顺序错了类型就断了。5.6 OAuth 相关报错如果你在 CLI 里集成了 OAuth 登录流程比如调用需要用户授权的接口可能会遇到OAuth token expired或refresh token invalid。这类问题的通用排查思路是检查 token 存储位置是否正确、refresh token 是否被覆盖、scope 是否匹配。对于 TaoToken 的 API Key 模式不涉及 OAuth 流程直接用 Bearer Token 即可相对简单。6. 继续扩展把 CLI 骨架用起来到这里一个可运行的 Commander TypeScript CLI 骨架就搭完了。你现在拥有的能力包括子命令注册与分发、必填/可选参数解析、选项默认值与校验、嵌套子命令、配置文件读写、模型 API 调用。接下来可以往几个方向扩展。第一加--verbose全局选项在program上用.option()定义然后在各 action 里通过program.opts()读取。第二给ask命令加流式输出把stream: true传给 API然后用for await逐块打印。第三加一个--config path选项支持自定义配置文件路径。第四用program.hook(preAction)做统一的初始化比如加载配置、检查 API Key 是否存在。如果你想深入模型调用相关的 CLI 场景可以看看 TaoToken 的接入文档 https://taotoken.net/doc 里面有不同语言的调用示例。需要长期跑编码类 Agent 任务的话Coding Plan https://taotoken.net/coding-plan 提供了更稳定的配额方案。想直接在网页上验证模型效果模型对话 https://taotoken.net/chat 可以快速试。CLI 工具的价值在于把重复操作固化下来。骨架搭好之后每加一个新命令的成本就是新建一个文件加几行注册代码。这套结构我用了好几个项目扩展到十几个子命令也没有变乱。你可以先把greet和config跑通然后照着ask的模式接入自己的业务逻辑。