CLI

shutdown-check CLI 有两个命令：init 生成一份初始配置；test 启动你的服务，并验证它收到 SIGTERM 之后的行为。

安装并查看帮助

npm install -D shutdown-check
npx shutdown-check --help

安装后，帮助信息如下：

shutdown-check — verify graceful shutdown with a real in-flight HTTP request
 
Usage:
  shutdown-check init [--config FILE]
  shutdown-check test [--config FILE] [--json] [--junit FILE]
  shutdown-check --help
  shutdown-check --version
 
Default config: shutdown-check.json
Exit codes: 0 passed, 1 shutdown check failed, 2 setup/configuration error

不带任何参数运行 shutdown-check，同样会打印帮助信息。

命令

用 init 生成配置

npx shutdown-check init

init 会在当前目录写入 shutdown-check.json。

用 --config 指定其他路径：

npx shutdown-check init --config config/shutdown-check.json

命令会打印生成的文件路径，并提醒你修改启动命令、端口和路由。它从不覆盖已有文件。如果目标文件已存在，CLI 会以退出码 2 退出：

shutdown-check: EEXIST: file already exists, open '/home/me/my-service/shutdown-check.json'

这时可以直接编辑已有文件、给它改名，或者换一个 --config 路径。生成的每个字段在配置参考中都有说明。

用 test 运行检查

npx shutdown-check test

test 会读取配置、执行启动命令、等待服务就绪、发起进行中的工作、发送 SIGTERM，然后检查响应和进程退出情况。

常见用法：

npx shutdown-check test
npx shutdown-check test --config config/shutdown-check.json
npx shutdown-check test --json
npx shutdown-check test --junit shutdown-result.xml
npx shutdown-check test --json --junit shutdown-result.xml

--config FILE

从其他路径读取配置。相对路径基于当前工作目录解析。配置文件内部的 cwd 则基于配置文件所在的目录解析。

--json

在 stdout 上输出完整的 JSON 结果，替代可读的文本输出。适合脚本处理和结构化的 CI 日志。进程的退出码不受影响。

--junit FILE

在文本或 JSON 输出之外，再写一份 JUnit XML 报告。父目录必须已经存在。这个文件会在正常结果打印之前写入。

--json 和 --junit 只属于 test。把它们传给 init 会被当作未知参数。

帮助和版本参数

npx shutdown-check --version

配置文件路径如何解析？

不传 --config 时，CLI 会从你运行命令的目录读取 shutdown-check.json。

假设目录结构如下：

my-service/
├── config/
│   └── shutdown-check.json
└── dist/
    └── server.js

运行：

npx shutdown-check test --config config/shutdown-check.json

如果服务的启动命令需要在 my-service/ 下运行，就在配置中写上 "cwd": ".."。

CLI 只接受 JSON。如果想用 TypeScript 写配置，请使用 Node API 中的 defineConfig() 和 checkShutdown()。

文本输出

默认输出包括：

1. PASS 或 FAIL，后面跟着诊断码和说明；
2. 时间线，时间是从本次运行开始算起的毫秒数；
3. 失败时，如果服务有 stderr 和 stdout 输出，附上各自最后 8 KiB。

FAIL SC101: Service exited before becoming ready: code 1
 
Timeline:
  +    7 ms  process launched — pid=74471
  +   47 ms  process exited — code=1, signal=none
  +  111 ms  check failed — SC101: Service exited before becoming ready: code 1
 
Service stderr (last 8 KiB):
Error: Cannot find module ./dist/server.js

先看诊断码，再看最后一个成功的时间线事件。诊断码页面列出了每种失败的原因和修复方法。

测试开始前的错误

命令行错误和配置错误都以 shutdown-check: 开头。因为测试根本没有运行，所以这类错误没有 SC 码，也没有时间线。

按症状分类的配置、启动和关闭问题，请参考故障排查。

退出码

• 0：服务满足配置的关闭约定，检查通过。
• 1：检查已运行，并返回了一个表示失败的 SC 码。
• 2：参数无效，或者出现环境或配置错误，导致检查无法进行。

退出码为 1 时，仍然可以写出 JSON 和 JUnit。退出码为 2 时没有测试结果，因此不会写 JUnit 报告。

其他包管理器

每条命令运行的都是当前项目中安装的版本。

相关内容

• 快速开始
• 配置参考
• 输出与报告
• 在 CI 中运行
• 故障排查