开始使用 WSL 容器

本分步指南介绍如何使用 WSL 内置的容器命令行工具 wslc.exe，在 Windows 上构建和运行 Linux 容器。

wslc.exe 提供熟悉的命令行界面，用于构建、交付和运行容器化应用。

WSL 容器概述

容器是一种用于创建、部署和运行应用的工具。它让开发者把应用所需的库、框架、依赖等组件打包为整体进行交付。运行应用的计算机可能与编写和测试代码的计算机具有不同的自定义设置或已安装库；使用容器可以让应用保持一致的运行方式，开发者因此能够专注于代码，无需操心代码将运行在哪套系统上。

先决条件

• 安装 WSL 2.9.3 或更高版本。运行 wsl --update 获取最新版本。
• 可选：安装 Visual Studio Code，以获得编写代码及调试连接到 Linux 发行版的容器化项目的体验。
• 可选：安装 Windows 终端，在同一界面定制和打开 Ubuntu、Debian、PowerShell、Azure CLI 等多个终端。

安装和验证 wslc

wslc.exe 随 WSL 提供，无需单独安装引擎。它要求 WSL 2.9.3 或更高版本。按以下步骤确认版本包含此功能：

1. 如果尚未安装，先安装 WSL，再打开 PowerShell 更新到最新版本：

   wsl --update

2. 确认 wslc.exe 可用并检查版本：

   wslc version

3. 运行一个简单的内置镜像来验证工作是否正常。如果镜像尚未在本地存在，工具会自动拉取：

   wslc run --rm hello-world

   预期出现一条“Hello”消息，表明安装看起来正常。

运行第一个容器

通过 wslc.exe 可以拉取镜像，在前台或后台运行容器，发布端口，以及与运行中的容器交互。在 PowerShell 中尝试以下命令：

# Run a command in a throwaway container
wslc run --rm -it ubuntu:latest bash -c "echo Hello world from WSL container!"

# Run a web server in the background and publish port 8080 to the container's port 80
wslc run -d --rm -p 8080:80 --name web nginx

# Request content from the running web server
curl localhost:8080

# List the running container
wslc container list

# Run an additional command inside the running container
wslc exec web cat /etc/os-release

# Stop the container
wslc container stop web

因为 nginx 容器使用 --rm 启动，它停止后会自动删除。

构建并运行自己的容器镜像

使用 wslc.exe 开发应用时，建议结合 VS Code 和 WSL 扩展，在 Linux 文件系统中编辑项目，并在集成终端运行 wslc 命令。

下面为一个现有应用项目构建容器镜像。

1. 本例使用 Python 开发环境配置文档中的 Django Hello World 教程源代码。如果使用自己的项目，可以跳过此步骤。打开 WSL 终端（例如 Ubuntu）下载 HelloWorld-Django Web 应用：

   git clone https://github.com/<username>/helloworld-django.git

2. 在 WSL 终端切换到项目源代码目录：

   cd helloworld-django

3. 打开运行于本地 WSL 扩展服务器的 VS Code 项目：

   code .

   检查 VS Code 左下角的绿色远程指示器，确认已连接到 WSL Linux 发行版。

   

4. 在项目根目录添加描述镜像构建方式的 Containerfile。Django 示例的最小文件可如下所示：

   FROM python:3
   WORKDIR /app
   COPY requirements.txt .
   RUN pip install --no-cache-dir -r requirements.txt
   COPY . .
   EXPOSE 8000
   CMD ["python", "manage.py", "runserver", "0.0.0.0:8000"]

5. 在包含 Containerfile 的项目目录中，用 wslc build 构建镜像，并添加便于后续引用的名称：

   wslc build -t helloworld-django .

6. 列出镜像，确认创建成功：

   wslc image list

7. 将新镜像作为容器运行，发布应用端口，以便从 Windows 访问：

   wslc run -d --rm -p 8000:8000 --name django helloworld-django

8. 列出运行中的容器并检查日志，确认容器正在运行：

   wslc container list
   wslc container logs django

9. 在 Windows 浏览器打开 http://localhost:8000/，查看运行在容器中的应用。也可在容器内执行命令，确认应用运行于 Linux：

   wslc exec django uname

   uname 返回“Linux”，表示容器运行于 WSL 2 Linux 内核之上。

10. 完成后停止容器：

    wslc container stop django

至此，这套流程使用由 WSL 2 支持的 wslc.exe 在 Windows 上完成 Linux 容器的构建和运行，并可结合 VS Code 进行构建、运行、部署或调试。

故障排除

检查容器或镜像

容器行为异常时，inspect 和 logs 命令提供详细信息，帮助诊断：

wslc container inspect <container-id>
wslc container logs <container-id>
wslc image inspect <image>

回收磁盘空间

镜像和已停止的容器会占用磁盘空间。清理不再使用的资源：

# Remove all stopped containers
wslc container prune

# Remove unused images
wslc image prune

一般的 WSL 故障排除帮助见故障排除文档。

其他资源

• WSL 容器概述
• WSL 容器 API 示例
• Microsoft Learn：容器简介
• VS Code 文档：在 WSL 中开发