如何在VSCode中调试Docker容器内的Next.js服务端代码

DevOps 小满

2026-7-3

解决VSCode调试Docker内Next.js服务端代码的问题

修正launch.json的调试端口
Node.js调试检查器默认使用9229端口，你当前配置里的port设为3000（这是应用服务端口），需要改成9229。修改后的配置如下：

{
  "name": "Docker: Attach to Node",
  "type": "node",
  "request": "attach",
  "port": 9229,
  "address": "localhost",
  "localRoot": "${workspaceFolder}",
  "remoteRoot": "/app",
  "protocol": "inspector"
}

确保Docker端口映射正确
要把容器内的9229端口映射到本地的9229端口：
- 如果用docker run命令，添加参数：-p 9229:9229 -p 3000:3000
- 如果用docker-compose，在对应服务下添加：
```
ports:
  - "3000:3000"
  - "9229:9229"
```
启动Next.js时开启调试模式
Next.js服务端代码需要在启动时开启调试监听，修改项目package.json里的dev命令：
```
"scripts": {
  "dev": "NODE_OPTIONS='--inspect=0.0.0.0:9229' next dev"
}
```
这里--inspect=0.0.0.0:9229指定调试器监听容器的所有网卡，确保本地能连接到容器内的调试端口。
验证代码路径映射匹配
确认容器内的/app目录和本地${workspaceFolder}的文件结构一致：
- 如果用挂载卷，确保docker-compose或run命令里的volume配置正确，比如：- ./:/app
- 如果用Dockerfile构建，确保COPY . /app命令正确复制了本地项目文件到容器的/app目录
检查调试端口连通性
运行容器后，在本地执行curl http://localhost:9229/json，如果返回包含调试会话信息的JSON，说明端口连通正常；如果连接失败，排查容器启动日志、端口映射是否生效。