使用 Docker 和 VS Code Dev Container 构建完美开发环境指南

06 Apr 2026

“在我电脑上运行正常啊？” 这句话是开发者协作时最常遇到的棘手问题之一。每个开发者的操作系统不同、安装的库版本有细微差异、各种环境变量设置不一，这些都可能导致无法预料的 bug，甚至拖累整个项目的进度。这类问题我们称之为“环境不一致”。

为了解决这个问题，容器技术应运而生，而其核心就是 Docker。Docker 将应用程序及其所有必需的依赖项打包到一个隔离的“容器”中，确保在任何环境下都能以相同的方式运行。开发者再也无需为开发环境和生产环境的差异而烦恼。

更进一步，Visual Studio Code 的 Dev Container 功能将 Docker 容器从一个单纯的运行环境，转变为一个完整的“开发环境”。它将 VS Code 编辑器本身连接到容器内部，让你可以像在本地环境开发一样，方便地编写代码、进行调试和使用终端。本文将详细分步介绍如何使用 Docker 和 VS Code Dev Container，为任何人、在任何操作系统上构建一个统一且可复现的开发环境。

为什么开发环境隔离如此重要？

假设一个新成员加入了项目团队。他需要在自己的笔记本电脑上安装项目所需的语言运行时（如 Python、Node.js）、数据库和各种库。在这个过程中，可能会出现以下问题：

操作系统 (OS) 差异： Windows、macOS 和 Linux 用户在安装过程、命令和路径等方面会遇到细微的差别。
依赖冲突 (Dependency Hell)： 系统全局安装的库版本可能发生冲突，例如项目 A 需要 Python 3.8，而项目 B 需要 3.10。
“配置的泥潭”： 需要手动匹配大量的环境变量和配置文件，这既耗时又容易出错。

这些问题最终都会导致“在我的电脑上可以，但在别人的电脑上不行”的情况，造成不必要的调试时间和整个团队生产力的下降。开发环境的隔离与标准化是从根本上解决这些问题的必要第一步。

Docker 容器：一致性的开端

Docker 将运行应用程序所需的一切（代码、运行时、系统工具、库等）打包成一个称为镜像 (Image) 的包。当这个镜像运行时，就成了一个名为容器 (Container) 的隔离进程。

其最大的优点是可移植性 (Portability)。只要安装了 Docker，任何地方都可以通过同一个镜像运行同一个容器。这意味着在开发者的笔记本电脑、测试服务器和实际的生产服务器上都能保证环境的一致性。通过一个名为 Dockerfile 的简单文本文件，可以用代码来定义所需的环境，使得环境配置本身也成为版本控制的一部分，变得透明且可复现。

VS Code Dev Container：革新开发体验

虽然 Docker 提供了出色的运行环境，但开发过程本身仍然在开发者的本地机器上进行。源代码在本地，编辑器也在本地运行。而 VS Code 的 Dev Container (Development Container) 扩展打破了这一界限。

使用 Dev Container，VS Code 会连接到指定的 Docker 容器内部，将该容器本身用作一个功能齐全的开发环境。

代码自动补全、Linter 和调试： VS Code 所有强大的功能都在容器内部直接运行。
终端： 打开 VS Code 内置终端时，你将直接访问容器的 shell，而不是宿主机的。
扩展插件： 开发所需的 VS Code 扩展也可以在容器内部隔离安装和运行。

也就是说，开发者无需在自己的电脑上安装任何与项目相关的工具或库，只需 Docker 和 VS Code，就能在容器内完成所有开发工作。

实战！构建 Dev Container 环境

现在，让我们实际为一个简单的 Node.js 项目构建一个 Dev Container 环境。

事前准备

首先，需要安装以下工具：

Docker Desktop： 安装适合您操作系统的版本。它能让您通过 GUI 轻松管理 Docker 引擎。(Docker Desktop 下载)
Visual Studio Code： 安装最新版的 VS Code。(VS Code 下载)
Dev Containers 扩展： 在 VS Code 市场中搜索 ms-vscode-remote.remote-containers 并安装。

第 1 步：创建项目文件夹并启动 VS Code

首先，为项目创建一个空文件夹，并用 VS Code 打开该文件夹。

mkdir my-dev-container-project
cd my-dev-container-project
code .

第 2 步：添加 Dev Container 配置文件

VS Code 打开后，按 F1 或 Ctrl+Shift+P(macOS: Cmd+Shift+P) 打开命令面板。然后输入并选择 Dev Containers: Add Dev Container Configuration Files...。

接着会显示各种语言和框架的模板列表。这里我们选择 Node.js & TypeScript。然后会提示选择版本，请选择你想要的版本（例如：18）。当出现选择要额外安装的功能 (features) 的窗口时，暂时先点击 OK 跳过。

第 3 步：分析生成的文件（.devcontainer 文件夹）

完成上述步骤后，项目根目录下会生成一个名为 .devcontainer 的文件夹，其中包含 devcontainer.json 文件和 Dockerfile。

devcontainer.json

这个文件是 Dev Container 的核心配置文件。

// .devcontainer/devcontainer.json
{
	"name": "Node.js & TypeScript",
	// 设置使用 Dockerfile 来构建镜像
	"build": {
		"dockerfile": "Dockerfile"
	},

	// VS Code 相关自定义配置
	"customizations": {
		"vscode": {
			"settings": {},
			// 在容器中要安装的 VS Code 扩展列表
			"extensions": [
				"dbaeumer.vscode-eslint"
			]
		}
	},

	// 容器创建后要执行的命令
	// "postCreateCommand": "npm install",

	// 主机与容器间的端口转发设置
	"forwardPorts": [3000],

	// 连接到容器时使用的用户
	"remoteUser": "node"
}

build.dockerfile：指定使用哪个 Dockerfile 来构建环境。
customizations.vscode.extensions：在此容器环境中将自动安装并激活的 VS Code 扩展 ID 列表。
forwardPorts：将容器内部的端口连接到本地机器的端口。在开发 Web 服务器时非常有用。
postCreateCommand：可以指定容器首次创建后自动执行的 shell 命令（例如：npm install）。

Dockerfile

这个文件是定义如何构建 Docker 镜像的脚本。

# .devcontainer/Dockerfile
# 基于官方 Node.js 镜像
FROM mcr.microsoft.com/devcontainers/typescript-node:0-18

# [可选] 可进行安装系统包等额外设置
# RUN apt-get update && export DEBIAN_FRONTEND=noninteractive \
#     && apt-get -y install --no-install-recommends <your-package-list-here>

这个 Dockerfile 基于微软提供的预构建的 Node.js 开发镜像。如果需要，你也可以使用 apt-get 等命令安装额外的系统库。

第 4 步：在容器中重新打开项目

配置文件创建完成后，VS Code 右下角会弹出一个通知：“Reopen in Container”。点击这个按钮。

如果错过了通知，也可以按 F1 打开命令面板，然后运行 Dev Containers: Reopen in Container。

现在，VS Code 将会基于 Dockerfile 构建 Docker 镜像，从该镜像启动容器，然后将 VS Code 后端服务器安装并连接到该容器内部。这个过程在首次运行时可能需要几分钟。

第 5 步：开始开发并检查环境

所有过程完成后，VS Code 窗口会重新打开。现在，你已经准备好在容器内进行开发了。

让我们打开 VS Code 的内置终端(Ctrl+ ``)。然后检查一下 Node.js 的版本。

node -v
# 输出: v18.x.x (Dockerfile中指定的版本)

现在，在这个终端中执行的所有命令（如 npm install、npm start）都不是在宿主机上运行，而是在完全隔离的 Docker 容器内部执行。现在，任何团队成员只需从 Git 克隆这个项目，然后点击“Reopen in Container”，就能在短短几分钟内拥有与你 100% 相同的开发环境。

Jiwon Min Developer