需借助 vscode 的 remote - containers 扩展实现本地编辑调试 docker 容器内代码，步骤包括安装扩展与 docker、基于镜像打开容器、配置 devcontainer.json、附加运行中容器及设置端口转发与调试。
如果您希望在本地使用 VSCode 直接编辑和调试运行于 Docker 容器内的代码，则需借助 VSCode 的 Remote - Containers 扩展实现容器内开发环境的无缝接入。以下是完成该连接的详细步骤：
本文运行环境：MacBook Pro，macOS Sequoia。
一、安装必要组件
Remote - Containers 功能依赖 VSCode 官方扩展与本地 Docker 运行时支持，需确保二者均已就位。
1、打开 VSCode，进入 Extensions 视图（快捷键 Cmd+Shift+X）。
2、搜索并安装 Remote - Containers 扩展（发布者为 Microsoft）。
3、确认本地已安装 Docker Desktop 并处于运行状态。
4、在终端中执行 docker --version 与 code --version，验证命令行可调用。
二、基于现有镜像打开容器
此方式适用于已有可用镜像（如 node:18、python:3.11），无需编写 Dockerfile，VSCode 将自动启动临时容器并挂载工作区。
1、在本地新建或进入一个项目文件夹，例如 my-web-app。
2、按下 Cmd+Shift+P 打开命令面板，输入并选择 Remote-Containers: Reopen in Container。
3、在弹出的镜像列表中选择目标镜像，例如 mcr.microsoft.com/vscode/devcontainers/python:3.11。
4、VSCode 将自动拉取镜像（如未缓存）、创建容器、安装 VSCode Server，并重载窗口至容器环境中。
三、使用自定义 devcontainer.json 配置
通过 devcontainer.json 可精确控制容器启动参数、端口转发、扩展预装及环境变量，适合团队统一开发环境。
1、在项目根目录下新建 .devcontainer 文件夹。
2、在该文件夹中创建 devcontainer.json，内容包含 image 或 build 字段，例如：
{ "image": "node:18", "forwardPorts": [3000], "customizations": { "vscode": { "extensions": ["esbenp.prettier-vscode"] } } }
3、按下 Cmd+Shift+P，执行 Remote-Containers: Reopen in Container。
4、VSCode 读取配置后，构建或拉取镜像，启动容器，并应用指定端口映射与扩展。
四、附加到正在运行的容器
当容器已由 docker run 或 docker-compose 启动且未使用 devcontainer 启动时，可通过附加方式接入，适用于调试生产镜像或遗留容器。
1、确保目标容器已运行，执行 docker ps 获取容器 ID 或名称。
2、按下 Cmd+Shift+P，输入并选择 Remote-Containers: Attach to Running Container...。
3、从列表中选择对应容器，VSCode 将尝试挂载其文件系统并部署 server。
4、若容器内无非 root 用户或缺少 curl/wget/zip 等基础工具，附加可能失败，需提前在容器中安装依赖。
五、配置端口与调试支持
容器内服务（如 Web 服务器、API）默认仅监听内部端口，需显式转发才能从宿主机访问，同时调试器需与容器内进程通信。
1、在 devcontainer.json 中添加 "forwardPorts": [5000, 8080] 字段，声明需暴露的端口。
2、启动容器后，在 VSCode 左下角状态栏点击 Ports，确认端口显示为“Forwarded”状态。
3、在容器内启动服务时，绑定地址必须为 0.0.0.0（而非 localhost 或 127.0.0.1），否则无法被转发。
4、调试配置（.vscode/launch.json）中，port 和 address 应匹配容器内监听设置，例如 "address": "0.0.0.0", "port": 9229。
