Serverless Framework 自定义 CLI 命令完全指南：Command 定义、生命周期事件与插件选项系统

Serverless Framework 本身就是一组"核心插件"的集合（见 插件总览），因此自定义插件与核心插件拥有完全相同的写法。其中最常见的扩展能力之一，就是通过插件注册自定义 CLI 命令（Custom commands）：插件定义好命令名称、参数与生命周期事件后，用户即可像使用内置命令一样直接运行 serverless my-command。本文基于 Custom commands 官方指南，结合当前仓库中插件加载与命令调度的真实源码，从命令骨架、生命周期钩子、CLI 选项到命名规范，逐层讲解如何开发一个可靠、可交付的自定义命令。

认识命令的三个基本概念：Command、Lifecycle Event 与 Hook

要理解自定义命令，先分清三个概念：

• Command（命令）：用户在终端调用的 CLI 入口，例如 serverless my-command。它本身不包含任何业务逻辑，只负责描述 CLI 配置（命令名、参数）和该命令的"生命周期事件"集合。
• Lifecycle Event（生命周期事件）：命令执行过程中被依次触发的事件节点。每个命令都可以定义属于自己的生命周期事件（如 resources、functions、run）。
• Hook（钩子）：真正挂载逻辑的地方。插件通过把回调函数注册到某个生命周期事件上，让命令在运行到该事件时执行你的代码。

一个最简自定义命令只包含 commands 定义：

class MyPlugin {
  constructor() {
    this.commands = {
      'my-command': {
        lifecycleEvents: ['resources', 'functions'],
      },
    }
  }
}

module.exports = MyPlugin

这段代码注册了一个 my-command，但此时命令"无任何逻辑"——只有当你为它的生命周期事件挂上 hooks 后，它才会真正做事情。

生命周期事件：给命令注入执行逻辑

命令默认没有逻辑，逻辑全部来自对生命周期事件的钩子。以下示例为 my-command 声明一个 run 事件，并注册对应 hook：

class MyPlugin {
  constructor() {
    this.commands = {
      'my-command': {
        lifecycleEvents: ['run'],
      },
    }

    this.hooks = {
      'my-command:run': () => {
        // Do something
      },
    }
  }
}

框架会为你在命令中声明的每一个事件自动生成一个 before 前缀事件和一个 after 前缀事件，因此上面一个 run 事件实际上展开为三个可挂载节点：

this.hooks = {
  'before:my-command:run': () => {
    // Before my command runs
  },
  'my-command:run': () => {
    // My command runs
  },
  'after:my-command:run': () => {
    // After
  },
}

注意：一个命令可以声明多个生命周期事件，这些事件会被按声明顺序依次调用。例如把 lifecycleEvents 定义为 ['check', 'deploy', 'report']，命令运行时会依次经过每个事件的 before → at → after 阶段。

源码视角：事件链是如何被调度执行的

在 plugin-manager.js 中可以找到这套机制的具体实现：

• loadHooks（plugin-manager.js#L731-L753）读取插件实例上的 hooks 对象，把每个事件名（含 before:/after: 前缀）与对应回调收集进管理器。
• getLifecycleEventsData（plugin-manager.js#L883-L903）为命令声明中的每个事件子名拼出完整事件名（${command.key}:${子事件名}），并取出 before、at、after 三组 hooks。
• invoke（plugin-manager.js#L922-L967）按顺序依次执行：before:<事件> → <事件> → after:<事件>，然后进入下一个生命周期事件。

这说明文档所讲的 before/after 规则不是文档层约定，而是框架执行引擎的固有行为，自定义命令与 deploy、package 等核心命令共用同一套调度内核。关于在核心命令（如 deploy:deploy）上挂 hook 的更多写法，可参考 Creating custom plugins。

为自定义命令声明 CLI 选项（Options）

命令可以声明自己的 CLI 选项，用户在使用时既可以双横线完整形式传参，也可以用单横线短选项：

• serverless my-command --function functionName
• serverless my-command -f functionName

选项需要在命令定义的 options 字段中显式声明，运行时通过插件构造器收到的 options 参数读取：

class MyPlugin {
  constructor(serverless, options) {
    this.options = options

    this.commands = {
      'my-command': {
        // The 'usage' property is used to display the 'serverless --help' output
        usage: 'This is my new custom command!',
        lifecycleEvents: ['run'],
        options: {
          // Define the '--function' option with the '-f' shortcut
          function: {
            usage:
              'Specify the function you want to handle (e.g. "--function myFunction")',
            shortcut: 'f',
            required: true,
            type: 'string', // Possible values: 'string', 'boolean', 'multiple'
          },
        },
      },
    }

    this.hooks = {
      'my-command:run': () => this.run(),
    }
  }

  run() {
    console.log('The option was: ', this.options.function)
  }
}

选项字段逐项说明

字段	作用	说明
usage	描述该选项用途	会显示在 serverless my-command --help 的帮助输出中；命令顶层的 usage 则用于 serverless --help 的命令列表
shortcut	定义短选项字母	例如 f，用户可用 -f 代替 --function
required	是否必填	true 时未传入会报错
type	取值类型	支持 'string'、'boolean'、'multiple'
default	默认值	当选项不是必填时可设置，未显式传入时使用

默认值是如何被写入的

源码层面的默认值处理在 assignDefaultOptions（plugin-manager.js#L1071-L1082）：当某个选项定义了 default，且用户没有传入该选项（或传入值等于 true 的布尔占位）时，管理器会将该默认值回填到 cliOptions。因此你可以在 hook 中放心读取 this.options.function，即便用户没有传参，它也会是你定义的默认值。

短选项的映射、参数解析与类型校验

• 短选项转换：用户输入的 -f value 如何变成 this.options.function？convertShortcutsIntoOptions（plugin-manager.js#L1054-L1069）在命令调用前把命令选项中 shortcut 对应的 CLI 原值映射到完整选项名。
• 命令行参数解析：parse-args.js 负责把原始 argv 分类为 boolean、string、multiple、别名等类型。对于 type: 'multiple' 的选项，多次传入会被收集成数组（例如 --tag a --tag b 得到 ['a', 'b']）；重复传入同名单值选项、或在需要取值的选项后缺失值，都会抛出对应错误。
• 选项合法性校验：ensure-supported-command.js 会逐一检查：选项是否为当前命令所支持、类型是否匹配（如 type: 'multiple' 要求最终为数组）、以及 required 选项是否缺失。这些校验意味着你声明的 usage、required、type 不是摆设——它们会被帮助文本与参数校验真正消费。

命令命名：全局唯一与冲突规避

命令名必须在所有插件之间保持全局唯一。 例如，不要去自定义一个名为 deploy 的命令，而应该命名为 my-company-deploy。原因在于 Serverless Framework 的 deploy 等命令由核心插件注册，如果插件定义的命令名与框架核心或其他插件冲突，CLI 会报错退出。

从源码看命名空间的实现：

• 所有插件（内置 + 外部）的命令最终都汇入 plugin-manager.js 的同一个 this.commands 注册表，通过 loadCommands（plugin-manager.js#L715-L729）装载。
• 对同名命令，mergeCommands（plugin-manager.js#L227-L252）采用"键级补全"式的合并策略：选项、子命令只在目标缺失时才补入，这导致同名命令的定义会在注册表层面被叠加——若两个插件对同名命令给出互相冲突的结构，最终行为难以预料。因此文档将"命令名唯一"作为铁律，而不是依赖框架替你兜底。
• 部分冲突会直接以错误形式抛出：同一插件类被重复加载会触发 DUPLICATE_PLUGIN_DEFINITION 错误（plugin-manager.js#L374-L380）；命令别名覆盖已有命令/别名会触发 INVALID_COMMAND_ALIAS、COMMAND_ALIAS_ALREADY_DEFINED 等错误（plugin-manager.js#L646-L685）。

实践上建议团队约定统一前缀（如公司名、产品名），把 my-command 这类通用词让给社区插件使用，从而在引入第三方插件时天然规避冲突。

把插件加载进服务并调用命令

自定义命令的宿主是插件。你可以把上面的类保存为本地文件（例如 my-plugin.js，CommonJS 写法需要 module.exports），然后在 serverless.yml 的 plugins 区通过无扩展名的本地相对路径加载：

# serverless.yml
service: app

functions:
  # ...

plugins:
  - ./my-plugin

保存后即可在服务目录中执行 serverless my-command（带选项则如 serverless my-command -f myFunction）。插件也支持 ESM 与 TypeScript 写法，并可发布到 NPM 供多项目复用，详见 Creating custom plugins；插件的安装与注册方式见 Plugins 指南。

延伸阅读

自定义命令只是插件扩展框架的入口之一，同属插件能力家族的还有：

• 通过 this.hooks 挂载到 deploy、package 等核心命令的生命周期事件（参考 Creating custom plugins，其中还介绍了 initialize 共享事件、build 标签排序与 provider 绑定）。
• 自定义变量源（见 Custom variables）与扩展 serverless.yml 语法/校验（见 Custom configuration 与 Extending configuration）。
• 向 CLI 输出写入额外信息（见 CLI output）。

理解了命令、生命周期事件、选项与命名四条主线后，你便掌握了 Serverless Framework 插件扩展最核心的一块拼图——自定义命令既能作为内部运维脚本（如批量清理、状态检查），也能包装成团队共享的工作流入口，且与核心命令共享同一套严谨的 CLI 参数校验与生命周期调度机制。