# SC001：端口已被占用

> SC001（端口已被占用）表示 shutdown-check 启动服务之前，配置的端口上已经有程序在响应。找出占用端口的进程，解决冲突。

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

`SC001` 表示启动前 `baseUrl` 中的端口已被占用。shutdown-check 无法把你的服务和已经在监听的进程区分开，所以直接停止。

| | |
| --- | --- |
| 诊断码 | `SC001` (FAIL) |
| 阶段 | 启动前 |
| CLI 退出码 | 1 |
| 含义 | 服务启动前，配置的端口上已经有程序在响应，检查无法把你的服务和它区分开。 |
| 输出信息 | `The local port at <origin> is already occupied or cannot be confirmed free; use a dedicated port` |
| 首先检查 | 给测试分配一个专用端口，并停掉仍在监听该端口的开发服务器或之前未结束的运行。 |

## 为什么会出现？

- 开发服务器还在运行。
- 另一个测试使用了同一个端口。
- 并行的 CI 任务共用同一个 `baseUrl`。
- 配置的端口属于数据库、代理或服务容器。
- 上一次运行留下了仍然存活的子进程。

## 如何修复？

1. 停止占用该端口的进程。
2. 给 shutdown-check 分配一个专供这个测试使用的端口。
3. 通过 `env` 把同一个端口传给服务。
4. 并行的测试使用不同的端口。

```json title="shutdown-check.json"
{
  "env": { "PORT": "3510" },
  "baseUrl": "http://127.0.0.1:3510"
}
```

如果问题出现在上一个测试之后，检查是否有启动器退出时没有停掉自己的子服务器。这个问题本身会在更后面的阶段报告为 [SC302](https://shutdown.jscrate.dev/zh/docs/codes/sc302)。

## 如何确认已修复？

用同样的命令再运行一次。时间线的第一个事件现在应该是 `process launched`，而不是 `check failed — SC001`。如果之后服务没能进入就绪状态，继续按 SC100 或 SC101 排查；端口冲突本身已经解决了。

如果只在 CI 中失败，检查并行任务和服务容器。本地空闲的端口，在 runner 上仍可能被共用。

## 相关内容

- [配置 `baseUrl` 和 `env`](https://shutdown.jscrate.dev/zh/docs/configuration#baseurl)
- [为每个测试分配独立端口](https://shutdown.jscrate.dev/zh/docs/guides/test-runners#give-every-test-its-own-port)
- [SC302：退出后端口仍未关闭](https://shutdown.jscrate.dev/zh/docs/codes/sc302)