基于VSCode的Node环境配合Testcontainers动态拉起Redis/MySQL测试-VSCode-PHP中文网

vscode中运行testcontainers测试前，docker必须被node进程识别：需确保docker cli在node环境path中、docker_host未误设、socket路径可访问，并正确使用gethost()与getmappedport()组合获取redis连接地址；mysql应优先用waitforhealthcheck()等待就绪；测试后须在afterall中显式stop容器并避免复用同名容器。

基于vscode的node环境配合testcontainers动态拉起redis/mysql测试

VSCode里跑Testcontainers测试前，Docker必须能被Node进程看见

Testcontainers-node 启动容器时依赖宿主机上的 docker CLI，不是靠 Docker Desktop GUI 或后台服务“自动生效”。很多人在 VSCode 终端里 docker --version 能跑，但用 node test/redis.test.js 就报 Error: connect ECONNREFUSED 127.0.0.1:2375 或 Cannot connect to the Docker daemon——本质是 Node 进程找不到 Docker socket。

常见原因和应对方式：

Windows 用户用 WSL2 时，docker 命令在 PowerShell/CMD 里可用，但 VSCode 默认终端可能是 WSL 子系统（或反过来），导致 PATH 不一致；确认 VSCode 终端的 shell 类型（右下角点击 Shell 类型切换），并确保它和你运行 docker --version 的环境一致
macOS 上 Docker Desktop 默认监听 unix:///var/run/docker.sock，但某些 VSCode 设置（如 Remote-SSH 或自定义 terminal.integrated.env.linux）会清空 PATH 或屏蔽 socket 路径；检查 process.env.DOCKER_HOST 是否为空，不为空就删掉它
Linux 用户若用 rootless Docker，需确保当前用户在 docker 组里，并且 ~/.docker/run/docker.sock 可读——Node 进程默认不继承 sudo 权限，别用 sudo node 启动测试

Redis 容器启动后，Node 应用连不上？重点查 `getMappedPort()` 和 host

本地开发时，Redis 容器暴露的端口（比如 6379）不会直接映射到宿主机 localhost:6379，而是由 Docker 动态分配一个高位端口（如 32784）。Testcontainers 提供 getMappedPort() 获取这个真实端口，但很多人误用 getHost() 返回值。

getHost() 在不同平台返回值不同：

macOS/Linux：返回 localhost（可直接用）
Windows + WSL2：返回 host.docker.internal（Docker 内部 DNS 名），但 Node 进程运行在 WSL 或 Windows 上，不一定能解析它；此时应改用 container.getHost() 返回的 IP（通常是 127.0.0.1）
如果用的是 Remote Container 扩展，getHost() 可能返回容器网络 IP（如 172.18.0.2），而你的 Node 进程在宿主机，必须用 localhost

稳妥写法：

const redisUrl = `redis://${container.getHost()}:${container.getMappedPort(6379)}`;

但更推荐显式 fallback：

MySQL（Linux）

MySQL 9.6.0是面向Linux平台的2026年创新版本，核心架构迎来重大革新。其将外键约束与级联操作从InnoDB引擎层上移至SQL层，确保所有数据变更均被完整记录至Binlog，彻底解决了CDC（变更数据捕获）与主从复制中的数据不一致难题。此外，该版本引入container_aware启动选项以原生适配容器环境，并对审计日志进行了组件化重构，为追求极致数据一致性与云原生体验的开发者提供了全新选择。

下载

const host = container.getHost() === 'host.docker.internal' ? 'localhost' : container.getHost();

MySQL 容器初始化慢，`waitForHealthcheck()` 比 `waitUntilReady()` 更可靠

MySQL 镜像启动后，mysqld 进程可能已运行，但数据库还没完成初始化（比如 root 密码设置、系统表加载），这时立刻连接会报 Connection refused 或 Access denied。Testcontainers-node 提供两种等待策略：

waitUntilReady()：只等容器状态为 running，不保证服务就绪——对 MySQL 来说基本没用
waitForHealthcheck()：依赖镜像内置的 HEALTHCHECK 指令（官方 mysql:8 镜像有），真正等数据库能响应 SQL 查询

实操建议：

务必加 .withHealthCheck({ interval: 1000, timeout: 3000, retries: 30 })，避免默认超时太短
不要自己写轮询逻辑（如 setInterval + mysql.createConnection），既冗余又难控制重试次数
如果用非官方镜像（比如带初始化 SQL 的定制镜像），确认它是否设置了 HEALTHCHECK；否则得用 withWaitStrategy(Wait.forLogMessage(...))

测试结束时容器没停干净，下次跑测试报端口冲突

Testcontainers 默认在 container.stop() 后清理资源，但 Node 进程异常退出（Ctrl+C、测试失败未 catch、Vitest watch 模式热重载）会导致容器残留。这些僵尸容器下次启动时可能占着映射端口，造成 address already in use 错误。

关键动作：

所有测试用例必须放在 afterAll(async () => { await container.stop(); }) 或 teardown 钩子里，不能只靠 test() 末尾调用
Vitest 用户注意：afterEach 不够，因为容器是跨测试复用的；要用 afterAll 并确保它执行（加 console.log 验证）
CI 环境（如 GitHub Actions）建议加预清理脚本：docker ps -q --filter "status=exited" | xargs -r docker rm，但本地开发更依赖钩子健壮性
调试时可手动查残留：docker ps --filter "ancestor=redis:8" --format "{{.ID}} {{.Status}}"