oclif — 给 50+ 命令的 CLI 一套"目录即路由"的框架

是什么

oclif（Open CLI Framework）是 Heroku 2018 年开源、后由 Salesforce 主导的 Node.js / TypeScript 命令行工具框架。日常类比：像盖大型连锁店时用的”加盟手册”——只要你照着规矩摆货架（按文件夹放命令文件），它就替你统一打招牌、写菜单、管收银。

你写：

src/commands/auth/login.ts

oclif 启动时自动把它注册成 mycli auth login 子命令，自动根据这个 class 的字段生成 --help，自动帮你做插件加载与冷启动缓存。

它不是”写两行就跑”的轻量库——而是企业级 CLI 的”基础设施层”，heroku CLI（200+ 命令）、Salesforce sfdx（500+ 命令）、Shopify CLI 都跑在它之上。

为什么重要

不理解 oclif，下面这些事都没法解释：

• 为什么 heroku CLI 几百条命令仍然 200ms 内启动——它做了 manifest 懒加载
• 为什么 sfdx 装个第三方 plugin 命令直接合并进主菜单——它有插件运行时
• 为什么大型 CLI 都长得”很像”（auth login / config get / help 风格）——oclif 把这些约定固化进了目录结构
• 为什么有人说”小项目千万别用 oclif”——它的甜区是 50+ 命令，小项目用是杀鸡用牛刀

核心要点

oclif 的架构可以拆成 三层：

1. 目录即命令（约定层）：src/commands/auth/login.ts 自动变成 mycli auth login，文件夹深度无限。类比：邮政地址——“省/市/街道/门牌”决定信件送到哪，不需要再单独写路由表。

2. Command class（抽象层）：每个命令是一个继承 Command 基类的 TypeScript class，把命令的 description / flags / args 写成 static 字段——这样 oclif 不用真的 new 出来就能读元数据。类比：每盒商品贴张外包装标签，仓管员不用拆盒就知道里面是什么。

3. plugin + manifest（运行时层）：插件是独立 npm 包，启动时被合并进同一张命令表；构建时生成的 oclif.manifest.json 缓存了所有命令的元数据，让运行时只在真正执行命令时才 require 对应文件——冷启动从秒级降到 200ms。

三层加起来就是 oclif 区别于 yargs / commander 的根本差异。

实践案例

案例 1：写第一个命令

import {Command, Flags, Args} from '@oclif/core'

export default class Hello extends Command {
  static description = '向某人打招呼'
  static flags = {
    name: Flags.string({char: 'n', description: '你的名字', required: true}),
  }
  static args = {
    person: Args.string({description: '打招呼对象', required: true}),
  }
  async run(): Promise<void> {
    const {args, flags} = await this.parse(Hello)
    this.log(`hello ${args.person} from ${flags.name}!`)
  }
}

逐部分解释：

• static description / flags / args 是 class 静态字段——oclif 不实例化也能读，用来生成 --help
• await this.parse(Hello) 把 process.argv 按 static 元数据解析成强类型对象
• this.log 而不是 console.log——框架提供统一输出 API，方便单元测试 mock

案例 2：BaseCommand 共享横切逻辑

实际项目里几乎所有命令都继承一个共享父类，把 API 客户端、auth 检查、错误转换提取到一处：

abstract class BaseCommand extends Command {
  protected client!: APIClient
  async init() {
    await super.init()
    this.client = new APIClient(process.env.API_KEY)
  }
  async catch(err: any) {
    if (err.code === 'UNAUTHORIZED') this.error('请先登录: mycli auth login')
    return super.catch(err)
  }
}

每个具体命令只重写 run()，登录失败的兜底逻辑写一次到处生效。这是 class 继承在 oclif 里的核心价值——函数式 CLI 框架（commander）做不到这种”生命周期 hook 共享”。

案例 3：manifest 缓存让 sfdx 启动从 3s 降到 80ms

500 命令的 sfdx 如果每次启动都 require 全部命令文件，光 TypeScript 编译产物加载就要数秒。oclif 在 npm publish 前跑 oclif manifest，把每条命令的 description / flags / args 序列化进 oclif.manifest.json：

{
  "commands": {
    "hello": {
      "description": "say hello",
      "flags": {"name": {"type": "option", "char": "n", "required": true}},
      "args": {"person": {"required": true}}
    }
  }
}

启动时只读这一个 JSON 就拿到全部 help 信息；用户真正执行 sfdx data:query 时，才 require() 那一个命令文件。这是 oclif 投资 “重型框架” 能换回来的硬收益——但也只在 100+ 命令规模才显现。

踩过的坑

1. 小项目用过头：< 20 命令用 oclif 几乎一定后悔——最小模板 30+ 文件、npm install 45s、新人 onboarding 两天。同样需求用 commander 200 行就够。

2. macOS 大小写陷阱：本地 Login.ts 能跑（默认大小写不敏感），推到 Linux CI 直接 “command not found”。oclif 命令必须全小写文件名。

3. manifest 忘了生成：dev 模式（bin/dev）走 ts-node 全量 require，没 manifest 也能跑；生产模式忘配 prepack 钩子会让冷启动崩盘。

4. process.exit 偷跑：自己 process.exit(1) 会让 oclif 的 finally hook 不跑，导致 telemetry buffer、DB 连接泄漏。用 this.error(msg, {exit: 1}) 代替，让框架处理退出。

适用 vs 不适用场景

适用：

• 命令数 50+ 且预期增长（heroku / sfdx / shopify 这种规模）
• 需要插件生态——允许第三方 npm 包扩展 CLI
• 需要跨平台 standalone binary（oclif/dev-cli 的 pack 命令）
• 团队 TypeScript first、有 dedicated CLI 维护人

不适用：

• 命令数 < 20 的内部脚本 → 用 commander / yargs
• 一次性脚本或周末 hack → oclif 半天才能搭起架子
• 启动时间敏感且没人优化资源 → 默认就有冷启动开销
• Node 版本受限场景（oclif 要 Node 18+）

模糊地带是 20-50 命令：稳定就 yargs，要继续长就 oclif。

历史小故事（可跳过）

• 2018：Heroku 内部 CLI 框架开源，命名 oclif
• 2019：sfdx 基于 oclif 重构，成为最大用户
• 2020：Salesforce 收购 Heroku，oclif 治理逐步转向 Salesforce 主导
• 2022：v2 发布——核心拆包成 @oclif/core，TypeScript-first 强化，把”只在生成项目时用”的 inquirer/yeoman 依赖剥离
• 2024-2025：持续迭代，主要由 Salesforce 工程师维护，新 CLI 应直接依赖 @oclif/core

治理风险提醒：开发节奏几乎跟着 Salesforce CLI 走，一些社区 PR 被搁置较久。选 oclif 之前评估”如果 Salesforce 转向，你还能不能 fork 接手”。

学到什么

1. 目录即路由是减法——把”写注册代码”这件事换成”放对位置”，是 Rails / Next.js / oclif 共享的设计哲学
2. 元数据 + 懒加载 是大型工具冷启动优化的通用解：构建时生成 manifest，运行时按需 require
3. 抽象 = 自由 - 灵活性：oclif 强约束让你写得快，代价是偏离约定就处处掣肘——这是所有”约定优于配置”框架的共同拐点
4. 选型先看规模：50+ 命令是 oclif 的临界质量，跨过去它帮你；跨不过去它压你

延伸阅读

• 官方文档：oclif.io（先读 Getting Started + Commands + Plugins 三章）
• GitHub：oclif/core（v2 后的核心，启动入口在 src/main.ts）
• 大规模实践：heroku CLI 仓库 / salesforcecli/cli
• 对比阅读：commander 和 yargs 的设计取舍——为什么它们不需要”目录即命令”
• 视频：YouTube 搜 “oclif tutorial” 有 Salesforce DX 官方 30 分钟入门

关联

• commander —— 极轻量 CLI 框架，链式 API，5-30 命令甜区，与 oclif 互补
• yargs —— 中等体量 CLI 框架，npm CLI / Vue CLI 都用，5-50 命令甜区
• typescript —— oclif v2 强制依赖，static 字段 + declaration merging 让 this.parse 自动推类型
• rollup —— 把 oclif CLI 打成 standalone binary 时常用的打包器
• heroku-cli —— oclif 的”原生”用户，200+ 命令的真实工程参照

反向链接

• aichat —— AIChat — 终端里的多模型 LLM 客户端
• chalk —— chalk — 让 console.log 输出彩色字符串的 Node 库
• commander —— commander.js — Node.js CLI 解析的声明式标准
• rollup —— Rollup — ESM 优先的打包器
• shell-gpt —— shell-gpt — 把 LLM 接进 shell 当命令行助理
• yargs —— yargs — Node.js 命令行参数解析的事实标准