在 WSL 2 上開始使用 Docker 遠端容器Get started with Docker remote containers on WSL 2

本逐步指南將協助您藉由 設定適用于 Windows 的 Docker Desktop (具有 WSL 2 (Windows 子系統 Linux 版第2版) )來開始開發遠端容器。This step-by-step guide will help you get started developing with remote containers by setting up Docker Desktop for Windows with WSL 2 (Windows Subsystem for Linux, version 2).

適用于 Windows 的 Docker Desktop 免費提供,並提供建立、交付和執行 docker 化應用程式的開發環境。Docker Desktop for Windows is available for free and provides a development environment for building, shipping, and running dockerized apps. 藉由啟用以 WSL 2 為基礎的引擎,您可以在相同電腦上的 Docker Desktop 中執行 Linux 和 Windows 容器。By enabling the WSL 2 based engine, you can run both Linux and Windows containers in Docker Desktop on the same machine.

Docker 容器概觀Overview of Docker containers

Docker 是一種工具,可用來建立、部署及執行使用容器的應用程式。Docker is a tool used to create, deploy, and run applications using containers. 容器可讓開發人員封裝含有其所需全部元件 (程式庫、架構、相依性等) 的應用程式,且全部以一個套件的形式出貨。Containers enable developers to package an app with all of the parts it needs (libraries, frameworks, dependencies, etc) and ship it all out as one package. 使用容器可確保應用程式會以相同的方式執行,而不管任何自訂的設定或先前在執行該應用程式的電腦 (可能與用來撰寫和測試應用程式程式碼的電腦不同) 上安裝的程式庫。Using a container ensures that the app will run the same regardless of any customized settings or previously installed libraries on the computer running it that could differ from the machine that was used to write and test the app's code. 這可讓開發人員專注於撰寫程式碼,而不需擔心程式碼將在其上執行的系統。This permits developers to focus on writing code without worrying about the system that code will be run on.

Docker 容器類似於虛擬機器,但不會建立整個虛擬作業系統。Docker containers are similar to virtual machines, but don't create an entire virtual operating system. 然而,Docker 可讓應用程式使用與系統執行所在的相同 Linux 核心。Instead, Docker enables the app to use the same Linux kernel as the system that it's running on. 這可讓應用程式套件只需要主機電腦上尚未存在的元件,以減少套件大小並提升效能。This allows the app package to only require parts not already on the host computer, reducing the package size and improving performance.

使用 Docker 容器搭配 Kubernetes 之類工具的持續可用性,是容器廣受歡迎的另一個原因。Continuous availability, using Docker containers with tools like Kubernetes, is another reason for the popularity of containers. 這可讓您在不同時間建立多個版本的應用程式容器。This enables multiple versions of your app container to be created at different times. 每個容器 (及其特定微服務) 都可以隨時被取代,而不需要關閉整個系統以便進行更新或維護。Rather than needing to take down an entire system for updates or maintenance, each container (and it's specific microservices) can be replaced on the fly. 您可以準備包含所有更新的新容器、設定用於生產的容器,並在準備就緒後直接指向新容器。You can prepare a new container with all of your updates, set up the container for production, and just point to the new container once it's ready. 您也可使用容器來封存不同版本的應用程式,並視需要使其以安全後援的形式執行。You can also archive different versions of your app using containers and keep them running as a safety fallback if needed.

若要深入瞭解,請參閱 Microsoft Learn 上的 Docker 容器簡介To learn more, checkout the Introduction to Docker containers on Microsoft Learn.



WSL 可以在 WSL 第1版或 WSL 2 模式中執行散發。WSL can run distributions in both WSL version 1 or WSL 2 mode. 您可以藉由開啟 PowerShell 並輸入:來檢查此項 wsl -l -vYou can check this by opening PowerShell and entering: wsl -l -v. 輸入下列內容,確定您的散發已設定為使用 WSL 2: wsl --set-version <distro> 2Ensure that the your distribution is set to use WSL 2 by entering: wsl --set-version <distro> 2. <distro>以發行版本名稱取代 (例如 Ubuntu 18.04) 。Replace <distro> with the distro name (e.g. Ubuntu 18.04).

在 WSL 第1版中,由於 Windows 和 Linux 之間的基本差異,Docker 引擎無法直接在 WSL 內執行,因此 Docker 團隊會使用 Hyper-v Vm 和 LinuxKit 開發替代解決方案。In WSL version 1, due to fundamental differences between Windows and Linux, the Docker Engine couldn't run directly inside WSL, so the Docker team developed an alternative solution using Hyper-V VMs and LinuxKit. 不過,因為 WSL 2 現在是在具有完整系統呼叫容量的 Linux 核心上執行,所以 Docker 可以在 WSL 2 中完整執行。However, since WSL 2 now runs on a Linux kernel with full system call capacity, Docker can fully run in WSL 2. 這表示 Linux 容器可以原生執行而不需要模擬,因此可讓您的 Windows 和 Linux 工具產生更佳的效能和互通性。This means that Linux containers can run natively without emulation, resulting in better performance and interoperability between your Windows and Linux tools.

安裝 Docker DesktopInstall Docker Desktop

使用適用于 Windows 的 Docker Desktop 中支援的 WSL 2 後端,您可以在以 Linux 為基礎的開發環境中工作,並建立以 Linux 為基礎的容器,同時使用 Visual Studio Code 進行程式碼編輯和偵測,並在 Windows 上的 Microsoft Edge 瀏覽器中執行您的容器。With the WSL 2 backend supported in Docker Desktop for Windows, you can work in a Linux-based development environment and build Linux-based containers, while using Visual Studio Code for code editing and debugging, and running your container in the Microsoft Edge browser on Windows.

若要在已 安裝 WSL 2) 之後安裝 Docker (:To install Docker (after already installing WSL 2):

  1. 下載 Docker Desktop ,並遵循安裝指示。Download Docker Desktop and follow the installation instructions.

  2. 安裝之後,請從 Windows [開始] 功能表啟動 Docker Desktop,然後從工作列的隱藏圖示功能表中選取 Docker 圖示。Once installed, start Docker Desktop from the Windows Start menu, then select the Docker icon from the hidden icons menu of your taskbar. 以滑鼠右鍵按一下圖示以顯示 [Docker 命令] 功能表,然後選取 [設定]。Right-click the icon to display the Docker commands menu and select "Settings". Docker 桌面儀表板圖示Docker Desktop dashboard icon

  3. 確定已在 [設定一般] 中選取 [使用以 WSL 2 為基礎的引擎] > ** **。Ensure that "Use the WSL 2 based engine" is checked in Settings > General. Docker Desktop 一般設定Docker Desktop general settings

  4. 從您要啟用 Docker 整合的已安裝 WSL 2 散發套件中,前往:設定 > 資源 > WSL 整合來進行選取。Select from your installed WSL 2 distributions which you want to enable Docker integration on by going to: Settings > Resources > WSL Integration. Docker Desktop 資源設定Docker Desktop resource settings

  5. 若要確認已安裝 Docker,請開啟 WSL 散發 (例如 Ubuntu) ,然後輸入下列內容來顯示版本和組建編號: docker --versionTo confirm that Docker has been installed, open a WSL distribution (e.g. Ubuntu) and display the version and build number by entering: docker --version

  6. 使用下列方法執行簡單的內建 Docker 映射,測試您的安裝是否正常運作: docker run hello-worldTest that your installation works correctly by running a simple built-in Docker image using: docker run hello-world


以下是一些實用的 Docker 命令來瞭解:Here are a few helpful Docker commands to know:

  • 輸入以下命令可列出 Docker CLI 中可用的命令:dockerList the commands available in the Docker CLI by entering: docker
  • 使用以下命令,列出特定命令的資訊:docker <COMMAND> --helpList information for a specific command with: docker <COMMAND> --help
  • 使用以下命令,列出電腦上的 Docker 映像 (此時就是 hello-world 映像):docker image ls --allList the docker images on your machine (which is just the hello-world image at this point), with: docker image ls --all
  • 列出您電腦上的容器,其中包含: docker container ls --alldocker ps -a (沒有-a show all 旗標,只會顯示執行中的容器) List the containers on your machine, with: docker container ls --all or docker ps -a (without the -a show all flag, only running containers will be displayed)
  • 列出有關 Docker 安裝的全系統資訊,包括您可以在 WSL 2 內容中使用的 (CPU & 記憶體) 的統計資料和資源,以及: docker infoList system-wide information regarding the Docker installation, including statistics and resources (CPU & memory) available to you in the WSL 2 context, with: docker info

使用 VS Code 在遠端容器中進行開發Develop in remote containers using VS Code

若要使用 Docker 搭配 WSL 2 來開始開發應用程式,我們建議使用 VS Code,以及 WSL 擴充功能和 Docker 延伸模組。To get started developing apps using Docker with WSL 2, we recommend using VS Code, along with the Remote-WSL extension and Docker extension.

  • 安裝 VS Code 遠端 WSL 延伸模組。Install the VS Code Remote-WSL extension. 此延伸模組可讓您在 VS Code 中開啟您在 WSL 上執行的 Linux 專案, (不需要擔心路徑問題、二進位相容性,或是其他) 的跨作業系統挑戰。This extension enables you to open your Linux project running on WSL in VS Code (no need to worry about pathing issues, binary compatibility, or other cross-OS challenges).

  • 安裝 VS code Remote-Containers 擴充功能。Install the VS code Remote-Containers extension. 此延伸模組可讓您在容器內開啟您的專案資料夾或存放庫,利用 Visual Studio Code 的完整功能集,在容器內執行您的開發工作。This extension enables you to open your project folder or repo inside of a container, taking advantage of Visual Studio Code's full feature set to do your development work within the container.

  • 安裝 VS Code Docker 延伸模組。Install the VS Code Docker extension. 此延伸模組新增了從 VS Code 內建立、管理及部署容器化應用程式的功能。This extension adds the functionality to build, manage, and deploy containerized applications from inside VS Code. (您需要 Remote-Container 擴充功能,才能實際使用容器做為開發環境。 ) (You need the Remote-Container extension to actually use the container as your dev environment.)

讓我們使用 Docker 為現有的應用程式專案建立開發容器。Let's use Docker to create a development container for an existing app project.

  1. 在此範例中,我將使用 Hello World 教學課程中的原始程式碼,在 Python 開發環境的設定檔中 進行 Django 。如果您想要使用自己的專案原始碼,可以略過此步驟。For this example, I'll use the source code from my Hello World tutorial for Django in the Python development environment set up docs. You can skip this step if you prefer to use your own project source code. 若要從 GitHub 下載我的 HelloWorld-Django web 應用程式,請 (Ubuntu 開啟 WSL 終端機,例如) ,然後輸入: git clone https://github.com/mattwojo/helloworld-django.gitTo download my HelloWorld-Django web app from GitHub, open a WSL terminal (Ubuntu for example) and enter: git clone https://github.com/mattwojo/helloworld-django.git


    一律將您的程式碼儲存在您要使用工具的相同檔案系統中。Always store your code in the same file system that you're using tools in. 這會導致檔案存取效能更快。This will result in faster file access performance. 在此範例中,我們使用 Linux 發行版本 (Ubuntu) ,而且想要將專案檔案儲存在 WSL 檔案系統上 \\wsl\In this example, we are using a Linux distro (Ubuntu) and want to store our project files on the WSL file system \\wsl\. 在 Windows 檔案系統上儲存專案檔,會在使用 WSL 中的 Linux 工具來存取這些檔案時,大幅降低效能。Storing project files on the Windows file system would significantly slow things down when using Linux tools in WSL to access those files.

  2. 從您的 WSL 終端機,將目錄變更為此專案的原始程式碼資料夾:From your WSL terminal, change directories to the source code folder for this project:

    cd helloworld-django
  3. 輸入下列內容,在本機遠端 WSL 延伸伺服器上執行的 VS Code 中開啟專案:Open the project in VS Code running on the local Remote-WSL extension server by entering:

    code .

    檢查 VS Code 實例左下角的綠色遠端指標,確認您已連線至 WSL Linux 發行版本。Confirm that you are connected to your WSL Linux distro by checking the green remote indicator in the bottom-left corner of your VS Code instance.

    VS Code WSL 遠端指示器

  4. 從 VS Code 命令面板 (Ctrl + Shift + P) ,輸入: 遠端容器:在容器中開啟資料夾 .。。如果您在開始輸入時未顯示此命令,請檢查以確定您已安裝上述連結的遠端容器擴充功能。From the VS Code command pallette (Ctrl + Shift + P), enter: Remote-Containers: Open Folder in Container... If this command doesn't display as you begin to type it, check to ensure that you've installed the Remote Container extension linked above.

    VS Code 遠端容器命令

  5. 選取您要將的專案資料夾。Select the project folder that you wish to containerize. 在我的案例中,這是 \\wsl\Ubuntu-20.04\home\mattwojo\repos\helloworld-django\In my case, this is \\wsl\Ubuntu-20.04\home\mattwojo\repos\helloworld-django\

    VS Code 遠端容器檔案夾

  6. 容器定義清單會隨即出現,因為專案資料夾 (存放庫) 尚未進行任何 DevContainer 設定。A list of container definitions will appear, since there is no DevContainer configuration in the project folder (repo) yet. 出現的容器設定定義清單會根據您的專案類型進行篩選。The list of container configuration definitions that appears is filtered based on your project type. 在我的 Django 專案中,我要選取 [Python 3]。For my Django project, I'll select Python 3.

    VS Code 遠端容器設定定義

  7. VS Code 的新實例隨即開啟、開始建立新的映射,完成組建之後,就會啟動我們的容器。A new instance of VS Code will open, begin building our new image, and once the build completed, will start our container. 您會看到新 .devcontainer 資料夾已在和檔案中顯示容器設定資訊 Dockerfile devcontainer.jsonYou will see that a new .devcontainer folder has appeared with container configuration information inside a Dockerfile and devcontainer.json file.

    VS Code. devcontainer 資料夾

  8. 若要確認您的專案仍同時連接至 WSL 和容器內,請開啟 VS Code 整合式終端機 (Ctrl + Shift + ~) 。To confirm that your project is still connected to both WSL and within a container, open the VS Code integrated terminal (Ctrl + Shift + ~). 輸入下列內容來檢查作業系統: uname 和 Python 版本 python3 --versionCheck the operating system by entering: uname and the Python version with: python3 --version. 您可以看到 uname 回傳為 "Linux",因此您仍然連線到 WSL 2 引擎,而 Python 版本號碼將會以容器設定為基礎,該設定可能與您在 WSL 發佈上安裝的 Python 版本不同。You can see that the uname came back as "Linux", so you are still connected to the WSL 2 engine, and Python version number will be based on the container config that may differ from the Python version installed on your WSL distribution.

  9. 若要使用 Visual Studio Code 在容器內執行和偵錯工具,請先開啟 [ 執行 ] 功能表 (Ctrl + Shift + D,或選取最左邊功能表列上的索引標籤) 。To run and debug your app inside of the container using Visual Studio Code, first open the Run menu (Ctrl+Shift+D or select the tab on the far left menu bar). 然後選取 [ 執行和調試 程式],以選取 [偵錯工具],並在我的範例中選擇最適合您專案 (的設定,這會是 [Django] ) 。Then select Run and Debug to select a debug configuration and choose the configuration that best suites your project (in my example, this will be "Django"). 這會 launch.json 在您的專案資料夾中建立檔案 .vscode ,以及如何執行應用程式的指示。This will create a launch.json file in the .vscode folder of your project with instructions on how to run your app.

    VS Code 執行 debug configuration

  10. 從 VS Code 中,選取 [執行 > 開始調試 (],或直接按F5鍵) 。From inside VS Code, select Run > Start debugging (or just press the F5 key). 這會開啟 VS Code 內的終端機,您應該會看到類似以下的結果:「在結束 伺服器時,使用 C + + 啟動開發伺服器」。This will open a terminal inside VS Code and you should see a result saying something like: "Starting development server at Quit the server with CONTROL-C." 按住 Ctrl 鍵並選取顯示的位址,以在預設網頁瀏覽器中開啟您的應用程式,並查看在其容器內執行的專案。Hold down the Control key and select the address displayed to open your app in your default web browser and see your project running inside of its container.

    執行 docker 容器 VS Code

您現在已成功設定遠端開發容器,並使用 WSL 2 後端所支援的 Docker Desktop,您可以使用 VS Code 來撰寫、建立、執行、部署或偵錯工具的程式碼!You have now successfully configured a remote development container using Docker Desktop, powered by the WSL 2 backend, that you can code in, build, run, deploy, or debug using VS Code!


WSL docker 內容已淘汰WSL docker context deprecated

如果您使用適用于 WSL 的 Docker 早期技術預覽,您可能會有一個稱為 "WSL" 的 Docker 內容,且該內容現在已淘汰且不再使用。If you were using an early Tech Preview of Docker for WSL, you may have a Docker context called "wsl" that is now deprecated and no longer used. 您可以使用下列命令來檢查: docker context lsYou can check with the command: docker context ls. 您可以移除此 "wsl" 內容,以避免命令發生錯誤: docker context rm wsl 因為您想要使用 Windows 和 WSL2 的預設內容。You can remove this "wsl" context to avoid errors with the command: docker context rm wsl as you want to use the default context for both Windows and WSL2.

您可能會在此已被取代的 wsl 內容中遇到的可能錯誤包括: docker wsl open //./pipe/docker_wsl: The system cannot find the file specified.error during connect: Get http://%2F%2F.%2Fpipe%2Fdocker_wsl/v1.40/images/json?all=1: open //./pipe/docker_wsl: The system cannot find the file specified.Possible errors you might encounter with this deprecated wsl context include: docker wsl open //./pipe/docker_wsl: The system cannot find the file specified. or error during connect: Get http://%2F%2F.%2Fpipe%2Fdocker_wsl/v1.40/images/json?all=1: open //./pipe/docker_wsl: The system cannot find the file specified.

如需此問題的詳細資訊,請參閱 Windows 10 上的如何在適用于 Linux 的 Windows 系統中設定 Docker (WSL2) For more on this issue, see How to set up Docker within Windows System for Linux (WSL2) on Windows 10.

找不到 docker 映射儲存體資料夾的問題Trouble finding docker image storage folder

Docker 會建立兩個發行版本資料夾來儲存資料:Docker creates two distro folders to store data:

  • \wsl $ \docker-desktop\wsl$\docker-desktop
  • \wsl $ \docker-desktop-data\wsl$\docker-desktop-data

您可以開啟 WSL Linux 散發套件,並輸入: explorer.exe . 在 Windows 檔案總管中查看資料夾,以找到這些資料夾。You can find these folders by opening your WSL Linux distribution and entering: explorer.exe . to view the folder in Windows File Explorer. 輸入: \\wsl\<distro name>\mnt\wsl <distro name> 將取代為您的散發名稱 (ie。Ubuntu-20.04) 查看這些資料夾。Enter: \\wsl\<distro name>\mnt\wsl replacing <distro name> with the name of your distribution (ie. Ubuntu-20.04) to see these folders.

若要深入瞭解如何在 WSL 中尋找 docker 儲存位置,請參閱 WSL 存放庫中 的這個問題 或此 StackOverlow 文章Find more on locating docker storage locations in WSL, see this issue from the WSL repo or this StackOverlow post.

如需 WSL 中一般疑難排解問題的詳細說明,請參閱 疑難排解 檔。For more help with general troubleshooting issues in WSL, see the Troubleshooting doc.

其他資源Additional resources