进阶 oclif.io 2026-10-18 02:37:03 · 22 阅读

第33章 oclif 入门:用 Node.js 构建 CLI 的可扩展框架

简介 oclif 是一个用于基于 Node.js 构建命令行接口(CLI)的框架。你可以简单地将它当作参数解析器使用,但它的功能远不止于此。该框架旨在具备可扩展性,让你可以轻松添加插件(例如更新警告插件),或自行开发插件供用户在运行时安装。 oclif 生成器可快速创建 TypeScript CLI 项目。生成的 CLI 运行时依赖极少,开销也很小。 oclif 的一切皆可自定义。甚至参数解析器和帮助信息生成都非强制,可随时替换。它是一个可在此基础上进行开发的平台,提供智能默认设置,且不会将你绑定到任何特定工具或行为模式。 要求 仅支持 LTS Node 版本。若希望确保用户使用的是特定 Node.js 版本,可在你的 CLI 中添加 node 包。 安装 oclif CLI 本身,请运行以下命令: $ npm install --global oclif
从零创建 oclif 项目 若要从零创建新的 oclif 项目,请运行 oclif generate 命令。 $ oclif generate mynewcli
Generating mynewcli in /Users/me/oclif/mynewcli
? Select a module type ESM
? NPM package name mynewcli
? Command bin name the CLI will export mynewcli


$ cd mynewcli
$ ./bin/dev.js hello world
hello world! (./src/commands/hello/world.ts)
该命令基于模板创建新项目。欲了解这些模板包含的内容,请参阅此处文档。 在 oclif generate 完成后,使用包含的 bin 脚本运行你的 CLI。 使用 bin/dev.js 以开发模式运行你的 CLI: $ ./bin/dev.js hello world
hello world! (./src/commands/hello/world.ts)
使用 bin/run.js 以生产模式运行你的 CLI: $ ./bin/run.js hello world
hello world! (./src/commands/hello/world.ts)
在现有项目中初始化 oclif 若希望在现有项目中开始使用 oclif,请使用 oclif init 命令添加必要的文件、依赖项和配置。 $ oclif init
? Command bin name the CLI will export (my-pkg): my-pkg
? Select topic separator: spaces
? Select a module type: CommonJS
? Select a package manager: npm

Created CLI in my-pkg
oclif init 会自动添加以下内容: bin 脚本:包括 bin/run.js、bin/run.cmd、bin/dev.js 和 bin/dev.cmd。更多详情请参阅 bin 脚本章节。 package.json 中的 oclif 配置块,包含 bin、dirname、commands 和 topicSeparator 属性。更多详情请参阅配置 CLI 章节。 将 @oclif/core 添加到 package.json 的 dependencies 属性中(如果尚未添加)。 将 ts-node 添加到 package.json 的 devDependencies 属性中(如果尚未添加)。 下一步 添加命令 生成 oclif 项目或在现有项目中初始化后,即可开始添加新命令。以下示例将创建一个新命令,并生成 TypeScript 源文件 src/commands/foo/bar.ts,你可以自定义该命令以执行任意操作: $ oclif generate command foo:bar
参阅 flags 和 args 文档了解如何为命令添加标志和参数;参阅 commands 文档了解命令支持的其他配置选项。 添加钩子 你还可以为 CLI 添加钩子,以进一步定制 CLI 的行为: $ oclif generate hook my-hook --event init
更多自定义选项 配置 CLI 自定义帮助 使用基础命令类 增强用户体验 其他教程 我们的伙伴 @joshcanhelp 在他的博客上撰写了一篇精彩的教程,强烈推荐阅读。

评论 (0)