现象
全量 API coverage 运行时,src/server.shutdown.test.ts 唯一失败:
Error: listen EADDRINUSE: address already in use 127.0.0.1:3000
❯ src/server.shutdown.test.ts:139 — server exited before listening
触发条件:本机有任何 dev API server 占着 3000 端口。CI(干净 runner)不受影响。
根因(as-built)
- 测试派生真实 server 子进程时设置
NODE_ENV=development + APP_PORT=String(childPort)(server.shutdown.test.ts:74-98,childPort 为 20000–40000 随机端口)。
- 但
apps/api/src/config/runtimeConfig.ts:416-423 的端口所有权开关规定:development 模式绑定 DEV_API_PORT(默认 3000),APP_PORT 被刻意忽略(防止遗留 .env 的 APP_PORT=3000 劫持 dev 端口)。
- 结果:子进程无视随机
APP_PORT,恒绑 3000 → 与运行中的 dev server 冲突,EADDRINUSE。
发现于 #669 Phase D1(PR #687)的全量 coverage 验证;与本分支无关(预先存在的测试隔离缺口),已按证据分类记录。
修复方向
spawn env 改设 DEV_API_PORT: String(childPort)(或让子进程进入显式尊重 APP_PORT 的模式),保持被测的 shutdown 生命周期契约不变。
Acceptance
Non-goals
- 不改
runtimeConfig.ts 的端口所有权开关本身。
- 不放宽测试超时/断言来掩盖冲突。
现象
全量 API coverage 运行时,
src/server.shutdown.test.ts唯一失败:触发条件:本机有任何 dev API server 占着 3000 端口。CI(干净 runner)不受影响。
根因(as-built)
NODE_ENV=development+APP_PORT=String(childPort)(server.shutdown.test.ts:74-98,childPort 为 20000–40000 随机端口)。apps/api/src/config/runtimeConfig.ts:416-423的端口所有权开关规定:development 模式绑定DEV_API_PORT(默认 3000),APP_PORT被刻意忽略(防止遗留.env的APP_PORT=3000劫持 dev 端口)。APP_PORT,恒绑 3000 → 与运行中的 dev server 冲突,EADDRINUSE。发现于 #669 Phase D1(PR #687)的全量 coverage 验证;与本分支无关(预先存在的测试隔离缺口),已按证据分类记录。
修复方向
spawn env 改设
DEV_API_PORT: String(childPort)(或让子进程进入显式尊重APP_PORT的模式),保持被测的 shutdown 生命周期契约不变。Acceptance
server.shutdown.test.ts绿)。Non-goals
runtimeConfig.ts的端口所有权开关本身。