进阶 oclif.io 2026-10-18 02:37:03 · 22 阅读
第21章 Oclif 框架错误处理机制详解
# 第21章 错误处理
错误处理 oclif 在两个地方处理故意抛出和非故意抛出的错误:先是在 Command 的 catch 方法中,最后在 bin/run.js 的 catch 处理器中,在那里错误会被打印出来,CLI 随之退出。这样的错误流转机制让你可以按自己的需要来控制和响应 CLI 中发生的错误。
## 在 catch 方法中处理错误
每个 Command 实例都有一个 catch 方法,命令运行过程中发生的错误都会触发它。该方法会处理用户请求帮助信息或版本信息这类特殊情况(如果适用),否则就把错误重新抛出。你可以在自己的命令类中扩展或重写 catch 方法。
import {Command, flags} from '@oclif/core'
export default class Hello extends Command {
async catch(error) {
// 做一些处理,或者
// 重新抛出,交给全局处理
throw error;
}
}
如果多个命令都需要实现同样的错误处理逻辑,建议使用 Custom Base Class,并在其中重写 catch 方法。 ## bin/run.js 的 catch 处理器 每个 oclif CLI 都有一个 ./bin/run.js 文件,它是命令调用的入口。CLI 中发生的错误(包括从 Command 中重新抛出的错误)都会被 oclif 的 handle 函数捕获并处理,由它把错误展示给用户。 如果你是用 oclif generate 生成 CLI 的,会看到一个 execute 函数,它负责运行 CLI 并捕获错误。当然,如果有定制错误处理的需求,你也可以自己实现这个逻辑。 oclif generate 生成的通用 bin/run.js 如下: #!/usr/bin/env node
import {execute} from '@oclif/core'
await execute({dir: import.meta.url})
要定制错误处理,需要改用 oclif 的 run 函数而不是 execute: #!/usr/bin/env node
import {run, handle, flush} from '@oclif/core'
await run(process.argv.slice(2), import.meta.url)
.catch(async (error) => handle(error))
.finally(async () => flush())
catch 处理器可以替换成任何接收 error 参数的函数。如果你选择在这里实现自己的处理逻辑,仍然建议在 finally 中委托给 handle 函数,由它负责清理和退出逻辑。 .catch((error) => {
// 对 error 做一些额外处理
return handle(error);
})
export default class Hello extends Command {
async catch(error) {
// 做一些处理,或者
// 重新抛出,交给全局处理
throw error;
}
}
如果多个命令都需要实现同样的错误处理逻辑,建议使用 Custom Base Class,并在其中重写 catch 方法。 ## bin/run.js 的 catch 处理器 每个 oclif CLI 都有一个 ./bin/run.js 文件,它是命令调用的入口。CLI 中发生的错误(包括从 Command 中重新抛出的错误)都会被 oclif 的 handle 函数捕获并处理,由它把错误展示给用户。 如果你是用 oclif generate 生成 CLI 的,会看到一个 execute 函数,它负责运行 CLI 并捕获错误。当然,如果有定制错误处理的需求,你也可以自己实现这个逻辑。 oclif generate 生成的通用 bin/run.js 如下: #!/usr/bin/env node
import {execute} from '@oclif/core'
await execute({dir: import.meta.url})
要定制错误处理,需要改用 oclif 的 run 函数而不是 execute: #!/usr/bin/env node
import {run, handle, flush} from '@oclif/core'
await run(process.argv.slice(2), import.meta.url)
.catch(async (error) => handle(error))
.finally(async () => flush())
catch 处理器可以替换成任何接收 error 参数的函数。如果你选择在这里实现自己的处理逻辑,仍然建议在 finally 中委托给 handle 函数,由它负责清理和退出逻辑。 .catch((error) => {
// 对 error 做一些额外处理
return handle(error);
})