Vendure项目CI测试中的端口冲突问题分析与解决方案

在Vendure电子商务平台的持续集成(CI)测试过程中，开发团队发现了一个影响测试稳定性的问题：不同测试套件之间偶尔会出现端口冲突，导致测试失败并显示EADDRINUSE错误。这个问题虽然看似简单，但其背后的原因和解决方案却值得深入探讨。

问题现象与影响

当多个测试套件并行运行时，某些测试会因尝试绑定已被占用的端口而失败。这种间歇性故障给CI流程带来了两个主要问题：

1. 掩盖了真正需要关注的测试失败（如特定Node.js版本或数据库的兼容性问题）
2. 增加了开发人员区分偶发故障和真实问题的认知负担

根本原因分析

问题的核心在于端口分配机制的设计缺陷。当前实现使用一个名为ports.json的临时文件来跟踪已使用的端口号。当多个测试进程同时读取这个文件时，会出现经典的竞态条件问题：

1. 进程A和进程B同时读取ports.json
2. 两者都获取到相同的"下一个可用端口"信息
3. 两者都尝试绑定该端口
4. 后启动的进程会因端口已被占用而失败

解决方案探索

开发团队尝试了几种不同的解决思路：

方案一：基于Vitest Worker ID的端口分配

最初尝试利用VITEST_WORKER_ID环境变量为每个测试工作线程分配唯一端口。然而，由于Vendure使用Lerna管理多包项目，会启动多个独立的Vitest进程，而VITEST_WORKER_ID只在单个Vitest进程内唯一。这个方案需要重构测试架构，让Vitest能够感知所有工作区并统一管理并行测试。

方案二：基于测试文件名的确定性端口分配

更可靠的解决方案是采用确定性端口分配策略：

1. 获取测试套件文件名
2. 按名称排序e2e目录中的所有测试文件
3. 根据当前测试文件在排序列表中的索引位置计算端口号
4. 使用基础端口号加上索引值得出最终端口

这种方法完全避免了竞态条件，因为：

• 不依赖共享状态（如ports.json文件）
• 使用同步文件系统操作确保一致性
• 每个测试套件总是获得相同的端口号

实施建议

对于类似问题的解决，建议采用以下最佳实践：

1. 避免共享状态：在并行测试环境中，尽量减少对共享资源的依赖
2. 确定性分配：使用可预测的算法分配测试资源（端口、临时文件等）
3. 隔离性设计：确保每个测试套件拥有独立的运行环境
4. 资源回收：即使测试失败也要确保释放所有分配的资源

总结

Vendure项目中遇到的这个CI测试问题很好地展示了并行测试环境中的常见陷阱。通过分析问题根源和探索不同解决方案，我们不仅解决了当前问题，也为类似场景提供了可借鉴的设计模式。确定性资源分配策略不仅适用于端口管理，也可以推广到其他需要隔离的测试资源分配场景中。