# CLI

> shutdown-check CLI 参考：init 和 test 两个命令、全部参数、配置文件的查找方式、文本输出格式，以及 0、1、2 三种退出码的含义。

Source: https://shutdown.jscrate.dev/zh/docs/cli
Last updated: 2026-09-23

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

## 安装并查看帮助

```bash
npm install --save-dev shutdown-check
npx shutdown-check --help
```

安装后，帮助信息如下：

```text
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` | 生成初始的 shutdown-check.json |
| `test` | 运行优雅关闭检查 |

## 用 init 生成配置

```bash
npx shutdown-check init
```

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

| 选项 | 作用 |
| --- | --- |
| `--config FILE` | 读取（`test`）或写入（`init`）这个配置文件，而不是 `shutdown-check.json`。文件里的路径相对于该文件所在的目录解析。 |

用 `--config` 指定其他路径：

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

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

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

这时可以直接编辑已有文件、给它改名，或者换一个 `--config` 路径。生成的每个字段在[配置参考](https://shutdown.jscrate.dev/zh/docs/configuration)中都有说明。

## 用 test 运行检查

```bash
npx shutdown-check test
```

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

| 选项 | 作用 |
| --- | --- |
| `--config FILE` | 读取（`test`）或写入（`init`）这个配置文件，而不是 `shutdown-check.json`。文件里的路径相对于该文件所在的目录解析。 |
| `--json` | 在 stdout 上以 JSON 输出完整结果，而不是文本时间线。 |
| `--junit FILE` | 同时向这个文件写入一份 JUnit XML 报告，其中包含一个测试用例。 |

常见用法：

```bash
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` 会被当作未知参数。

## 帮助和版本参数

| 参数        | 简写 | 行为                                  |
| ----------- | ---- | ------------------------------------- |
| `--help`    | `-h` | 打印帮助；必须是第一个参数            |
| `--version` | `-v` | 打印已安装的版本；不能带任何其他参数  |

```bash
npx shutdown-check --version
```

## 配置文件路径如何解析？

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

假设目录结构如下：

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

运行：

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

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

CLI 只接受 JSON。如果想用 TypeScript 写配置，请使用 [Node API](https://shutdown.jscrate.dev/zh/docs/node-api) 中的 `defineConfig()` 和 `checkShutdown()`。

## 文本输出

默认输出包括：

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

```text
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
```

先看诊断码，再看最后一个成功的时间线事件。[诊断码页面](https://shutdown.jscrate.dev/zh/docs/codes)列出了每种失败的原因和修复方法。

## 测试开始前的错误

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

| 示例消息                                                                                                      | 如何修改                   |
| ------------------------------------------------------------------------------------------------------------- | -------------------------- |
| `Unknown command "run". Run shutdown-check --help.`                                                           | 使用 `init` 或 `test`      |
| `Unknown option "--verbose". Run shutdown-check --help.`                                                      | 去掉不支持的参数           |
| `--config requires a file path`                                                                               | 在 `--config` 后面加上路径 |
| `--junit requires a file path`                                                                                | 在 `--junit` 后面加上路径  |
| `Cannot read JSON config /path/shutdown-check.json: Error: ENOENT: no such file or directory, open '/path/…'` | 修正路径或创建该文件       |
| `baseUrl must use http://localhost, http://127.0.0.1 or http://[::1]`                                         | 使用支持的本地地址         |

按症状分类的配置、启动和关闭问题，请参考[故障排查](https://shutdown.jscrate.dev/zh/docs/troubleshooting)。

## 退出码

| 退出码 | 含义 |
| --- | --- |
| `0` | 通过 |
| `1` | 关闭检查失败 |
| `2` | 环境或配置错误 |

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

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

## 其他包管理器

| npm                       | pnpm                            | Yarn                       | Bun                        |
| ------------------------- | ------------------------------- | -------------------------- | -------------------------- |
| `npx shutdown-check test` | `pnpm exec shutdown-check test` | `yarn shutdown-check test` | `bunx shutdown-check test` |

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

## 相关内容

- [快速开始](https://shutdown.jscrate.dev/zh/docs/quick-start)
- [配置参考](https://shutdown.jscrate.dev/zh/docs/configuration)
- [输出与报告](https://shutdown.jscrate.dev/zh/docs/output)
- [在 CI 中运行](https://shutdown.jscrate.dev/zh/docs/ci)
- [故障排查](https://shutdown.jscrate.dev/zh/docs/troubleshooting)