进阶 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 - 默认标题中以