进阶 oclif.io 2026-10-18 02:37:03 · 21 阅读
第16章 oclif 命令发现策略
# 第16章 命令发现策略
oclif 在加载插件时,需要找到该插件中所有可执行的命令。发现这些命令有三种策略:
- pattern —— 默认行为,基于 glob 模式查找命令
- explicit —— 从指定文件中查找导出的命令
- single —— 整个 CLI 只有一个命令,由顶层 bin 执行
## pattern 策略
pattern 策略让 oclif 使用一组预定义的 glob 模式,在指定目录中查找命令文件。除非另有说明,这是 oclif 的默认行为。
插件可以把 commands 属性指向一个目录:
{
"oclif": {
"commands": "./dist/commands",
}
}
这样 oclif 就会在该目录中查找命令(如果存在 oclif.manifest.json,则会跳过这一步)。 你也可以用下面的配置达到完全相同的效果: {
"oclif": {
"commands": {
"strategy": "pattern",
"target": "./dist/commands"
}
}
}
此外,你还可以设置 globPatterns,覆盖 oclif 在搜索命令文件时使用的 glob 模式: {
"oclif": {
"commands": {
"strategy": "pattern",
"target": "./dist/commands",
"globPatterns": [
"/*.+(js|cjs|mjs|ts|tsx|mts|cts)",
"!/*.+(d.*|test.*|spec.*|helpers.*)?(x)"
]
}
}
}
如果你习惯把测试文件或辅助文件和命令文件放在同一个目录下,这个功能会很有用。 ## explicit 策略 explicit 策略让 oclif 从单个文件中导入命令。此时 target 是导出命令的文件,identifier 是导出的名称(默认为 default)。 使用时需要新建一个文件(例如 src/commands.ts),然后在 package.json 中添加如下配置: {
"oclif": {
"commands": {
"strategy": "explicit",
"target": "./dist/index.js",
"identifier": "COMMANDS",
}
}
}
之后 src/index.ts 需要导出一个与 identifier 同名的对象(未设置时默认为 default),该对象以命令名为键、命令类为值,例如: import Hello from './commands/hello'
import HelloWorld from './commands/hello/world'
export const COMMANDS = {
hello: Hello,
'hello:world': HelloWorld,
howdy: Hello, // 将 `hello` 命令别名为 `howdy`
}
显式策略对于那些无法依赖文件路径的用户非常有用,例如他们已经对代码进行了打包(参见“打包”部分)。它同样适用于你更希望明确指定命令,而非依赖 oclif “神奇地”从文件系统自动发现命令的场景。 此外,你还可以利用显式策略在运行时创建或修改命令(例如在运行时进行消息国际化,或根据 API 规范为命令添加标志——参见下方的“动态命令”部分)。 Hooks(钩子) 可以使用显式策略来定义 Hooks: "oclif": { "hooks": { "init": { "target": "./dist/index.js", "identifier": "INIT_HOOK" } } } // src/index.ts import Hello from './commands/hello' import HelloWorld from './commands/hello/world' export {default as INIT_HOOK} from './hooks/init/init.js' export const COMMANDS = { hello: Hello, 'hello:world': HelloWorld, howdy: Hello, // 将 `hello` 命令别名映射为 `howdy` } 该配置实际上是在告诉 oclif 去查找 `./dist/index.js` 文件中的 `INIT_HOOK` 导出。 打包(Bundling) 由于可用的工具及配置组合无穷无尽,我们并不支持打包。但如果你选择使用如 esbuild 这样的打包工具,有几个硬性要求:必须在根目录中包含 `package.json`,并且 `bin/run` 或 `bin/run.js` 需为 bin 脚本。这意味着你无法将完整的 CLI(源代码、`package.json`、`node_modules` 等)成功打包为单个文件。 如果你仍希望使用打包工具,可以参考此示例仓库。 动态命令(Dynamic Commands) 如果你想在运行时操纵或创建命令,也可以使用显式策略。请注意,这种使用显式策略的方式不能与 `oclif.manifest.json` 一起使用,这对 CLI 在生产环境中的性能会产生重大影响。 示例: // src/index.ts import {Command, Flags} from '@oclif/core' import Hello from './commands/hello' import HelloWorld from './commands/hello/world' const dynamicCommands: Record = {}
if (process.env.DYNAMIC_COMMAND) {
dynamicCommands[process.env.DYNAMIC_COMMAND] = class extends Command {
static flags = {
flag1: Flags.boolean({description: 'flag1 description'}),
}
async run(): Promise {
const {flags} = await this.parse(this.constructor as Command.Class)
this.log('hello from', this.id, flags)
}
}
}
export const COMMANDS = {
hello: Hello,
'hello:world': HelloWorld,
...dynamicCommands,
}
❯ DYNAMIC_COMMAND=foo:bar:baz bin/run.js foo bar baz --flag1
hello from foo:bar:baz { flag1: true }
single Strategy single 策略告知 oclif,该 CLI 仅包含一个命令,可通过 bin/run.js 执行(例如 ls 或 cat)。 {
"oclif": {
"commands": {
"strategy": "single",
"target": "./dist/index.js"
}
}
}
在此例中,./dist/index.js 导出命令类。 关于 oclif.manifest.json 对于所有策略,都将使用 oclif.manifest.json 来加载命令,而非默认的 strategy 行为。
"oclif": {
"commands": "./dist/commands",
}
}
这样 oclif 就会在该目录中查找命令(如果存在 oclif.manifest.json,则会跳过这一步)。 你也可以用下面的配置达到完全相同的效果: {
"oclif": {
"commands": {
"strategy": "pattern",
"target": "./dist/commands"
}
}
}
此外,你还可以设置 globPatterns,覆盖 oclif 在搜索命令文件时使用的 glob 模式: {
"oclif": {
"commands": {
"strategy": "pattern",
"target": "./dist/commands",
"globPatterns": [
"/*.+(js|cjs|mjs|ts|tsx|mts|cts)",
"!/*.+(d.*|test.*|spec.*|helpers.*)?(x)"
]
}
}
}
如果你习惯把测试文件或辅助文件和命令文件放在同一个目录下,这个功能会很有用。 ## explicit 策略 explicit 策略让 oclif 从单个文件中导入命令。此时 target 是导出命令的文件,identifier 是导出的名称(默认为 default)。 使用时需要新建一个文件(例如 src/commands.ts),然后在 package.json 中添加如下配置: {
"oclif": {
"commands": {
"strategy": "explicit",
"target": "./dist/index.js",
"identifier": "COMMANDS",
}
}
}
之后 src/index.ts 需要导出一个与 identifier 同名的对象(未设置时默认为 default),该对象以命令名为键、命令类为值,例如: import Hello from './commands/hello'
import HelloWorld from './commands/hello/world'
export const COMMANDS = {
hello: Hello,
'hello:world': HelloWorld,
howdy: Hello, // 将 `hello` 命令别名为 `howdy`
}
显式策略对于那些无法依赖文件路径的用户非常有用,例如他们已经对代码进行了打包(参见“打包”部分)。它同样适用于你更希望明确指定命令,而非依赖 oclif “神奇地”从文件系统自动发现命令的场景。 此外,你还可以利用显式策略在运行时创建或修改命令(例如在运行时进行消息国际化,或根据 API 规范为命令添加标志——参见下方的“动态命令”部分)。 Hooks(钩子) 可以使用显式策略来定义 Hooks: "oclif": { "hooks": { "init": { "target": "./dist/index.js", "identifier": "INIT_HOOK" } } } // src/index.ts import Hello from './commands/hello' import HelloWorld from './commands/hello/world' export {default as INIT_HOOK} from './hooks/init/init.js' export const COMMANDS = { hello: Hello, 'hello:world': HelloWorld, howdy: Hello, // 将 `hello` 命令别名映射为 `howdy` } 该配置实际上是在告诉 oclif 去查找 `./dist/index.js` 文件中的 `INIT_HOOK` 导出。 打包(Bundling) 由于可用的工具及配置组合无穷无尽,我们并不支持打包。但如果你选择使用如 esbuild 这样的打包工具,有几个硬性要求:必须在根目录中包含 `package.json`,并且 `bin/run` 或 `bin/run.js` 需为 bin 脚本。这意味着你无法将完整的 CLI(源代码、`package.json`、`node_modules` 等)成功打包为单个文件。 如果你仍希望使用打包工具,可以参考此示例仓库。 动态命令(Dynamic Commands) 如果你想在运行时操纵或创建命令,也可以使用显式策略。请注意,这种使用显式策略的方式不能与 `oclif.manifest.json` 一起使用,这对 CLI 在生产环境中的性能会产生重大影响。 示例: // src/index.ts import {Command, Flags} from '@oclif/core' import Hello from './commands/hello' import HelloWorld from './commands/hello/world' const dynamicCommands: Record
}
}
}
export const COMMANDS = {
hello: Hello,
'hello:world': HelloWorld,
...dynamicCommands,
}
❯ DYNAMIC_COMMAND=foo:bar:baz bin/run.js foo bar baz --flag1
hello from foo:bar:baz { flag1: true }
single Strategy single 策略告知 oclif,该 CLI 仅包含一个命令,可通过 bin/run.js 执行(例如 ls 或 cat)。 {
"oclif": {
"commands": {
"strategy": "single",
"target": "./dist/index.js"
}
}
}
在此例中,./dist/index.js 导出命令类。 关于 oclif.manifest.json 对于所有策略,都将使用 oclif.manifest.json 来加载命令,而非默认的 strategy 行为。