文档教程【免费下载链接】vscode-docsPublic documentation for Visual Studio Code项目地址https://gitcode.com/gh_mirrors/vs/vscode-docs点击查看免费下载导读开发容器化应用时排查构建与运行时问题通常只能借助docker exec -it containerID /bin/sh进入容器命令行这种方式虽然能看到环境却无法使用完整的编辑器能力。本指南基于 VS Code 官方博客与 Dev Containers 附加容器文档演示如何借助Dev Containers 扩展把本地 VS Code 附加Attach到任何运行中的 Docker 容器从而在容器内部获得与本地一致的编辑、代码导航、调试和扩展管理体验。读完本文你将掌握「构建示例应用 → 附加到容器 → 打开容器内源码 → 断点调试 → 安装容器内扩展 → 清理环境」的完整实战链路并能看懂附加容器配置文件如express-server.json的每个字段。为什么需要把 VS Code 附加到容器当容器化应用出现问题时最常见的临时排查手段是在宿主机上执行docker exec -it {containerID} /bin/sh这条命令能让你在容器内获得一个交互式 Shell从而查看进程、文件与环境变量。但它存在明显的短板你只有命令行这一种工具。没有语法高亮、没有智能感知IntelliSense、没有代码导航更没有图形化调试器排查效率十分有限。VS Code 的Dev Containers扩展扩展 IDms-vscode-remote.remote-containers2019 年 5 月发布解决了这一问题它可以让你的本地 VS Code 连接到一个容器宿主环境同时完整保留你自己的个性化设置、主题与快捷键。附加Attach模式下你连接的不是由 VS Code 为你创建的新容器而是已经运行中的、以任意方式启动的容器——无论它来自docker run、docker-compose up还是 CI 产物。附加成功后你就可以在容器环境里做任何本地能做的事打开文件、搜索引用、启动调试器、安装扩展。架构本质附加容器时VS Code 会先在该容器内安装并启动一个VS Code Server远程后端本地 VS Code 客户端再与之建立连接。这一机制与 VS Code Server 文档 描述的远程后端完全一致——本地界面负责渲染容器内服务负责执行编译、调试、文件读写等重活。前置条件本文以 2019 年 10 月 31 日发布的官方博客作者 Bowden Kelly为基础撰写运行环境要求如下已安装 Docker DesktopWindows/macOS或 Linux 上的 Docker CE/EE 18.06已安装 VS Code已安装Dev Containers扩展。安装方式打开扩展视图kb(workbench.view.extensions)即CtrlShiftX/CmdShiftX搜索 Dev Containers点击Install如被提示则重启 VS Code。关于系统与容器兼容性参考仓库中的 Developing inside a Container 文档Windows 10 Pro/Enterprise 需 Docker Desktop 2.0Windows 10 Home (2004) 需 Docker Desktop 2.3 且启用 WSL 2 后端容器镜像方面支持 x86_64 / ARMv7l / ARMv8l 的 Debian 9、Ubuntu 16.04、CentOS/RHEL 7 以及 x86_64 Alpine Linux 3.9。需要特别留意的是使用 Alpine Linux 容器时部分扩展可能因原生代码依赖glibc而无法工作见 attach-container.md 中的警告。准备示例应用为了演示附加流程我们需要一个能在容器中运行的应用。如果你手上已有现成的容器化应用可以跳过本节否则可以克隆官方示例应用vscode-express-sample一个简单的 Node.js Express 应用git clone vscode-express-sample 仓库注意本地不需要安装 Node.js——整个应用都将在容器内运行该示例应用包含两个关键文件Dockerfile基于 Node 10 官方镜像构建docker-compose.yml负责构建镜像、暴露相应端口、并将本地文件系统挂载mount进容器。在docker-compose.yml中应用以--inspect参数启动 Node 进程这样我们就能像调试本地应用一样调试容器内应用。博客原文特别提醒真实生产项目中通常应为生产部署单独准备一份 Docker Compose 文件例如不挂载源码、不以 inspect 模式启动。另外附加容器并不强制要求 Docker Compose——通过单个 Dockerfile 创建的容器同样可以附加。构建并运行容器先安装依赖再从终端/命令提示符执行docker-compose up该命令会完成三件事下载 Node 基础镜像、拷贝依赖、启动容器。如果一切正常你会看到类似下面的输出随后在浏览器中访问 http://localhost:3000应能看到 Express 的欢迎页面此时容器已在运行且端口 3000 已通过 Compose 暴露到宿主机。注意容器内文件系统与本地是隔离的但由于 Compose 配置了本地目录挂载我们在容器内编辑的文件会直接持久化到本地磁盘——这正是后面「编辑即持久化」实验的前提。附加到运行中的容器现在开始使用 Dev Containers 扩展附加到刚才启动的容器。通过 Remote Explorer 附加点击活动栏Activity Bar中的Remote Explorer在Other Containers博客当时版本/Containers当前文档版本见 attach-container.md分区中可以看到所有正在运行的容器列表找到刚才启动的容器其名称为express_server_1该名称由 Compose 项目名express与服务名server拼接而来点击该容器条目上的Connect to Container连接到容器按钮。附加成功后该容器会出现在 Remote Explorer 的Attached Containers分区中另一种等价方式直接打开命令面板kb(workbench.action.showCommands)即F1运行Dev Containers: Attach to Running Container...命令从列表中选择目标容器。VS Code Server 的安装与连接点击连接按钮后会打开一个全新的 VS Code 窗口实例右下角会出现Installing Dev Container正在安装 Dev Container通知在这段时间里VS Code 正在你的应用容器内部安装一份VS Code Server。想要查看安装进度详情可以点击通知中的details链接。一旦安装完成本地 VS Code 客户端就会连接到远程 VS Code Server整体架构如下架构要点结合 VS Code Server 文档VS Code Server运行在容器内的后端服务是远程体验的基础负责文件系统、语言服务、调试适配器等后端逻辑本地客户端你的本地 VS Code保留所有个性化设置、主题、快捷键只负责 UI 渲染与交互连接建立后你的本地实例与运行在容器内的后端协同工作形成本地界面 远程后端的开发形态。连接完成后新窗口左下角会出现绿色指示器提示当前 VS Code 实例运行在远程上下文中。点击该指示器会弹出与当前远程上下文相关的命令下拉列表打开容器内的源码文件夹点击Open Folder打开文件夹按钮导航到/usr/src/app。请注意这个打开文件夹对话框展示的是运行中容器的文件系统而不是本地文件系统打开源码文件夹后编辑器中会自动打开一个名为express-server.json的文件。这个文件名的来历是由所附加容器的镜像名派生——在本例中docker-compose 依据文件夹名express和docker-compose.yml中的服务名server生成了镜像名express_server于是附加配置文件就叫express-server.json。理解附加容器配置文件express-server.json是一份与当前镜像关联的附加容器配置文件会记住你在附加到基于该镜像的容器时的各项配置如果你没有开启自动保存Auto Save务必手动保存该文件保存后未来再次附加到该镜像的容器时VS Code 会自动重新打开这个源码文件夹你随时可以通过命令面板kb(workbench.action.showCommands)运行Open Container Configuration File打开容器配置文件来查看当前附加容器对应的配置文件。博客年代版本的配置文件内容大致如下{ workspace: /usr/src/app, extensions: [] }版本演进说明博客2019 年示例中的键名为workspace在仓库当前的 附加容器配置文档 中该属性已统一为workspaceFolder并扩展了更多受支持属性详见下文「附加容器配置文件参考」。两者含义相同指定附加时默认打开的容器内路径。与本地无异的编辑体验附加完成后VS Code 界面与普通本地窗口别无二致你可以在容器上下文中做任何本地 VS Code 能做的事。例如打开app.js在第 8 行右键执行Find All References查找所有引用查看usersRouter的所有使用位置编辑文件并保存——编辑会持久化到本地磁盘因为 docker-compose 已将本地文件系统挂载进容器。在容器内调试为了进一步说明开发容器与本地环境的高度一致下面演示如何附加调试器。由于docker-compose.yml中已经以--inspect参数启动了 Node 进程我们只需把调试器附加到该进程即可打开命令面板kb(workbench.action.showCommands)搜索并执行Debug: Attach to Node Process调试附加到 Node 进程容器内通常有多个 Node 进程选择运行我们应用的那个——特征是在列表中显示为bin/www的进程打开index.js在第 6 行res.render(index, { title: Express });左侧装订线处点击或按下kb(editor.debug.action.toggleBreakpoint)F9设置断点res.render(index, { title: Express });回到浏览器访问 http://localhost:3000断点将按预期触发这一流程与本地调试完全一致断点命中、单步、变量查看、调用栈等能力全部可用。从仓库文档看容器内调试是 Dev Containers 的一等公民——containers.md 明确指出在容器中打开文件夹后可以像本地一样使用launch.json启动配置并启动调试器应用在远程宿主容器上启动、调试器随之附加。在容器中安装扩展与普通 VS Code 实例一样附加到 Dev Container 后也可以安装和使用扩展。关键在于理解扩展的两种运行位置客户端侧UI 侧主要是 UI 类扩展如主题、代码片段它们留在本地客户端运行容器内远程 VS Code Server 侧其余所有扩展都安装在容器中。这样的设计让你能在不同环境里只安装各自需要的扩展同时在整个环境中保持一致的 UI。打开扩展视图kb(workbench.view.extensions)会看到两组列表本地已安装扩展Local - Installed与当前容器实例中已安装的扩展。本地已安装、但需要在容器中运行的扩展如下图的 Azure Account 扩展会以置灰状态显示补充在 containers.md 中这一行为有更完整的描述——本地已安装但实际需要远程运行的扩展会在Local - Installed分类中显示为Disabled点击Install即可将其安装到远程宿主容器上你也可以通过Install Local Extensions in Dev Container: {名称}按钮将本地已安装的扩展批量装进容器。实战安装 GitLens以 GitLens 扩展扩展 IDeamodio.gitlens为例在扩展视图搜索框输入gitlens选择Install in Attached Container在附加容器中安装安装会提示重启 VS Code重启后会短暂出现Installing Dev Container通知——因为容器与 VS Code Server 会带着新安装的扩展一起重启同时之前见过的容器配置文件会重新打开并更新新增一个extensions属性记录每次附加到该镜像时希望自动安装的扩展{ workspace: /usr/src/app, extensions: [ eamodio.gitlens ] }现在打开任意文件、选中一行代码即可看到 GitLens 提供的行内 Git 信息扩展与配置的进阶知识结合当前仓库的 Dev Containers 文档 与 附加容器配置文档还有几个与「在容器中管理扩展」直接相关的实用能力始终安装的扩展Always installed extensions如果希望某些扩展在任何容器中都自动安装可以在用户settings.json中配置dev.containers.defaultExtensions设置项。例如将 GitLens 与 Resource Monitor 设为始终安装dev.containers.defaultExtensions: [ eamodio.gitlens, mutantdino.resourcemonitor ]强制扩展运行位置Advanced扩展通常被设计为在某一侧运行。若某个扩展同时支持可在settings.json中使用remote.extensionKind强制指定运行位置。例如强制 Container Tools 在本地ui运行、Remote - SSH 配置文件编辑器在远程workspace运行remote.extensionKind: { ms-azuretools.vscode-containers: [ ui ], ms-vscode-remote.remote-ssh-edit: [ workspace ] }警告ui/workspace的强制切换可能破坏扩展功能通常仅用于测试除非扩展文档另有说明。附加容器配置文件参考附加容器配置文件是 Dev Containers 工作流中容易被忽视、却非常实用的部分。依据仓库中的 Attached container configuration reference这类文件支持devcontainer.json属性的一个子集属性类型说明workspaceFolderstring连接到容器时 VS Code 默认打开的路径通常指向容器内的源码挂载点。默认不设置打开空窗口。extensionsarray指定容器创建时应安装的扩展 ID 数组。默认[]。settingsobject向容器/机器特定设置文件注入默认settings.json值。forwardPortsarray需要从容器转发到本地机器的端口列表。portsAttributesobject将端口号、host:port、端口范围或正则表达式映射为一组默认选项例如portsAttributes: {3000: {label: Application port}}。otherPortsAttributesobject未在portsAttributes中配置的端口/范围/主机的默认选项例如otherPortsAttributes: {onAutoForward: silent}。remoteEnvobject为 VS Code或终端等子进程设置/覆盖环境变量的键值对不影响容器整体环境。值中可引用环境变量如remoteEnv: { PATH: ${containerEnv:PATH}:/some/other/path }。remoteUserstring覆盖 VS Code 在容器中运行所使用的用户连同终端、任务、调试等子进程。默认使用容器整体运行的用户通常为root。userEnvProbeenum探测用户环境变量所使用的 Shell 类型none、interactiveShell、loginShell、loginInteractiveShell默认。例如 bash 交互式 Shell 会包含/etc/bash.bashrc与~/.bashrc中的变量登录式 Shell 则包含/etc/profile与~/.profile中的变量。postAttachCommandstring / arrayVS Code 附加到容器后要运行的命令。字符串可用连接多条命令如apt-get update apt-get install -y curl数组语法[yarn, install]则不经 Shell 直接调用命令。配置文件中的可用变量变量适用属性说明${containerEnv:VAR_NAME}remoteEnv容器运行后内部已存在的环境变量此处为VAR_NAME的值。例如remoteEnv: { PATH: ${containerEnv:PATH}:/some/other/path }。一份完整的附加容器配置示例当前文档格式如下{ // 默认打开路径 workspaceFolder: /usr/src/app, // 容器创建时设置的默认 settings.json 值 settings: { terminal.integrated.defaultProfile.linux: bash }, // 希望安装的扩展 ID extensions: [ eamodio.gitlens ], // 要转发的端口 forwardPorts: [3000], // 连接时使用的容器用户 remoteUser: vscode, // 为 VS Code 及子进程设置环境变量 remoteEnv: { MY_VARIABLE: some-value } }文件级image-level与名称级name-level配置默认采用镜像级配置即express-server.json这种按镜像名命名的文件附加后运行Dev Containers: Open Container Configuration File可查看/更新它。若希望把配置绑定到容器名称附加后可运行Dev Containers: Open Named Configuration File打开命名配置文件此后更新将作用于名称级配置。已保存的配置会在下次以相同镜像/容器名附加时自动生效即使未附加容器也可通过Dev Containers: Open Attached Container Configuration File...命令选择镜像/容器名来编辑。相关细节如果希望无论附加到哪个容器都安装某些扩展可参考上文dev.containers.defaultExtensions设置。此外若应用监听在容器内的某个端口但未在 Compose 中发布也可通过命令面板的Forward a Port命令临时转发该端口remote.restoreForwardedPorts设置为true可让 VS Code 记住已转发的端口详见 containers.md。清理资源调试结束后按以下步骤清理运行命令面板中的Close Remote Connection关闭远程连接命令或直接关闭 VS Code 窗口即可终止远程连接在终端/命令提示符中执行docker-compose down该命令会停止正在运行的容器释放内存与已占用的端口。之后你就可以随时启动另一个容器、投入下一个项目。进阶阅读与下一步本指南演示了如何用 Dev Containers 扩展附加到现有容器化应用进行检视与调试。如果你希望更进一步仓库中还提供了以下资源devcontainer.json 入门创建一份描述开发环境的devcontainer.json随项目一起存放、与团队成员共享让团队获得一致的开发环境Developing inside a ContainerDev Containers 的完整文档涵盖系统要求、安装、三类快速上手试用示例容器 / 打开已有文件夹 / 以隔离卷打开 Git 仓库或 PR以及端口转发、终端、调试等主题Advanced container configuration环境变量、本地磁盘挂载、非 root 用户、多容器连接等进阶容器配置方案Dev Containers 入门教程从零开始构建隔离开发环境的分步教程Attach to a running container附加容器的权威参考包含附加到 Kubernetes 集群容器的方式运行Dev Containers: Attach to Running Kubernetes Container...或借助 Kubernetes 扩展与kubectl在集群资源上右键附加注意附加配置文件暂不支持 Kubernetes 集群中的容器。Happy Remote Coding!赞分享文档教程【免费下载链接】vscode-docsPublic documentation for Visual Studio Code项目地址https://gitcode.com/gh_mirrors/vs/vscode-docs点击查看免费下载相关推荐VS Code 开发容器实战在 Docker 容器中构建、运行并调试 Code - OSSVS Code 开发容器实战在 Docker 容器中构建、运行并调试 Code OSS Visual Studio Code 仓库内置了一套完整的 Dev C开发工具代码编辑器Aspire VS Code 扩展实战运行与调试 AppHost 完整指南Aspire VS Code 扩展实战运行与调试 AppHost 完整指南 本指南围绕 Aspire VS Code 扩展的“运行你的应用”Run your云原生后端微服务可观测性开发工具Playwright VS Code 扩展入门在编辑器内运行、调试与自动生成端到端测试Playwright VS Code 扩展入门在编辑器内运行、调试与自动生成端到端测试 Playwright 官方 VS Code 扩展把 Playwrigh测试开发工具浏览器控制上一篇Electron Architecture Rules下一篇简单三步搭建终极家庭游戏串流中心Sunshine完全指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考