VS Code Dev Containers 端口怎么配置或排查

VS Code Dev Containers 里端口打不开，通常不是“浏览器坏了”，而是容器端口没有被转发，或者应用实际监听的端口与配置不一致。最稳妥的做法是先在容器终端确认监听端口，再在 .devcontainer/devcontainer.json 中写入 forwardPorts，最后通过 Ports 面板确认本地地址。

官方地址：https://code.visualstudio.com/docs/devcontainers/containers

第一步：先确认容器内真正监听的端口

先打开 VS Code 的远程容器终端，执行下面的示例命令。这里假设 Web 服务应该使用容器内的 3000 端口；如果项目使用 8080，就把筛选条件一并改成 8080。

# 查看容器内正在监听的 TCP 端口，先确认应用实际使用哪个端口
ss -lntp | grep ':3000'

# 转发完成后，用本机地址检查 HTTP 响应；这里只验证示例地址
curl -I http://localhost:3000

能看到监听记录，说明应用至少已经绑定了端口；如果没有任何结果，先启动开发服务器。若结果显示的是另一个端口，后续配置应以这个端口为准。

第二步：用 forwardPorts 固定自动转发

在资源管理器中打开项目的 .devcontainer/devcontainer.json，把 forwardPorts 加到顶层配置。下面是最小配置；严格 JSON 不写注释，字段含义放在代码块外解释。

{
  "name": "node-dev",
  "image": "mcr.microsoft.com/devcontainers/javascript-node:1-22-bookworm",
  "forwardPorts": [3000],
  "portsAttributes": {
    "3000": {
      "label": "Web 服务",
      "onAutoForward": "notify"
    }
  }
}

forwardPorts 是要从容器转发到本机的端口列表；多个服务可以写成 [3000, 5173]。portsAttributes 只负责给端口设置标签和自动转发时的提示行为，不会替代应用监听。保存文件后执行 F1 → Dev Containers: Reopen in Container，让配置在新的容器连接中生效。

第三步：没有改配置时，用 Ports 面板临时转发

如果只是临时查看一个测试服务，不必先修改项目文件。按 F1 打开命令面板，选择 Dev Containers: Forward a Port，输入容器内的 3000，确认后打开底部的 PORTS 面板。

也可以在 PORTS 面板点击添加端口，输入 3000。成功状态应能看到端口号、转发状态和本地地址；点击本地地址即可在浏览器中测试。这个转发只跟随当前会话，想让团队成员打开项目后自动获得同样配置，仍应回到第二步写入 devcontainer.json。

第四步：按三项检查定位端口异常

端口仍打不开时，按下面的顺序检查，通常不需要盲目更换端口号。

还要分清“端口转发”和 Docker 的端口发布：前者是 VS Code 连接开发容器时把容器端口提供给本机，后者是 Docker 或 Compose 层面的网络映射。开发阶段只想在本机打开页面，优先使用 forwardPorts；需要改变容器对外网络拓扑时，再检查 Compose 的 ports 配置。

相关问题

为什么 forwardPorts 写成宿主机端口后仍然打不开？

它描述的是容器内端口，先确认服务在容器内监听的数字，再把这个数字写入数组。宿主机最终使用哪个本地地址，以 Ports 面板显示为准。

修改 devcontainer.json 后必须重建容器吗？

端口转发这类连接配置通常先执行 Reopen in Container；如果镜像、Feature 或 Dockerfile 也发生变化，再按提示选择 Rebuild Container。

端口已显示 Forwarded，为什么浏览器还是空白？

Forwarded 只说明转发通道建立，不保证应用有响应。回到容器终端确认进程仍在运行，并用本机地址执行一次 curl -I，再查看服务日志。