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

第19章 配置 CLI

配置 CLI

你可以通过在 CLI 或插件的 package.json 中使用 rc 文件来配置 oclif 的行为。

如果使用 package.json,所有配置项都需放在 oclif 字段下。示例:

{
  "name": "my-cli",
  "version": "1.2.3",
  "dependencies": {
    "@oclif/core": "^3"
  },
  "oclif": {
    "bin": "mycli",
    "dirname": "mycli",
    "commands": "./dist/commands",
    "topicSeparator": " "
  }
}

如果想使用 rc 文件,配置项无需再包裹在 oclif 中。示例:

//.oclifrc.js

module.exports = {
  bin: "mycli",
  dirname: "mycli",
  commands: "./dist/commands",
  topicSeparator: " "
}

支持的 rc 文件包括:

.oclifrc
.oclifrc.json
.oclifrc.js
.oclifrc.mjs
.oclifrc.cjs
oclif.config.js
oclif.config.mjs
oclif.config.cjs
以下是你可以配置的所有选项。 属性 | 说明 additionalHelpFlags | 除 --help 之外,能触发帮助输出的标志数组 additionalVersionFlags | 除 --version 之外,能触发版本输出的标志数组 aliases | 插件的别名,用于支持已改名的旧插件 bin | CLI 的 bin 名称(如 sf、heroku、git 等) binAliases | 一组字符串,都可以用来执行 CLI 的 bin。详见 Aliases dirname | 确定 CLI 的配置、缓存和数据目录时使用的目录名 commands | oclif 查找命令类的位置。详见 Command Discovery Strategies description | 在帮助中显示的插件或 CLI 描述 devPlugins | 仅在开发环境下加载的插件列表。详见 Plugins exitCodes | 配置退出码。见下方 Exit Codes 部分 flexibleTaxonomy | 设为 true 以启用 flexible taxonomy helpClass | 编译后的自定义帮助类位置 helpOptions | 帮助输出行为的配置项。见下方 Help Options 部分 hooks | 注册插件或 CLI 的 hooks。详见 hooks jitPlugins | 注册可即时安装的插件。详见 Just-in-Time Plugin Installation macos | 构建 macos 安装包的配置。详见 Releasing nsisCustomization | 用于自定义 Windows 安装器的 .nsis 文件路径。详见 nsis-custom plugins | 应加载的插件列表。详见 Plugins state | 设置 CLI 或插件的状态并在帮助中显示(如 beta 会显示 This CLI is in beta) theme | 随 CLI 一起包含的主题文件路径。详见 Themes topicSeparator | 主题之间的分隔符,仅支持冒号(":")和空格(" ") topics | 定义 CLI 的主题。详见 Topics windows | 构建 Windows 安装包的配置。详见 Releasing Exit Codes​ 你可以为以下错误配置期望的退出码: default - 任何错误的默认退出码。 failedFlagParsing - oclif 解析 flag 值失败时的退出码。 failedFlagValidation - flag 自身校验失败时的退出码。 invalidArgsSpec - 命令定义了无效的 args 配置时的退出码。 nonExistentFlag - 用户传入不存在的 flag 时的退出码。 requiredArgs - 用户未提供必需的 arg 时的退出码。 unexpectedArgs - 用户给命令传入多余参数时的退出码。 Help Options​ 你可以通过以下选项配置帮助输出的行为: docopts - 使用 docopts 作为 usage。默认为 true。 flagSortOrder - 帮助输出中 flag 的排序方式。可选 alphabetical(默认)或 none(按定义顺序显示)。 hideAliasesFromRoot - 设为 true 时,在根帮助输出中隐藏命令别名。默认为 false。 hideCommandSummaryInDescription - 默认情况下,命令摘要会显示在帮助顶部,同时作为命令描述的第一行。在描述中重复摘要有助于提高可读性,尤其是较长的命令帮助输出。如果没有 command.summary,描述的第一行会被视为摘要。有些 CLI(尤其是命令非常简单的)可能不想要这种重复。 maxWidth - 帮助输出的最大列宽。 sections - 只显示指定部分的帮助。默认显示所有部分。 sendToStderr - 默认帮助输出到 stdout,设为 true 时输出到 stderr。 showFlagNameInTitle - 默认标题中以 形式显示 flag 值。有些 CLI 开发者更希望标题中用 flag 名称作为值,即显示 --myflag=myflag 而不是 --myflag=。单个 flag 可通过 flag.helpValue=flag.name 设置。 showFlagOptionsInTitle - 默认情况下,flag 的选项值显示在 flag 的描述中,因为过长的选项列表会破坏帮助的排版。如果 CLI 确定所有命令都不会出现这个问题,可以通过此属性在帮助层面关闭该行为。单个 flag 可通过 flag.helpValue=options.join('|') 设置。 stripAnsi - 从帮助输出中去除 ansi 字符,移除所有格式。 usageHeader - 覆盖 USAGE 部分的标题。 如果想进一步自定义帮助,可以实现一个 Custom Help Class。

评论 (0)