WSL Containers（wslc）完整安装与使用复盘手册
WSL Containers（wslc）完整安装与使用复盘手册
引用资料前置
Windows WSL2 虚拟硬盘迁移终极方案：Junction 一劳永逸，告别 C 盘焦虑
在WSL-podman-machine-default (Fedora Linux 42) 中安装 CUDA 13.0、cuDNN 9.14、Anaconda 2025.06、PyTorch 2.10
在WSL2-Ubuntu中安装Anaconda、CUDA13.0、cuDNN9.12及PyTorch（含完整环境验证）
【打造 AI 开发环境系列】WSL 路径治理必做篇：先迁移，再开发，别让 C 盘爆满！
【理念●体系】从零打造 Windows + WSL + Docker + Anaconda + PyCharm 的 AI 全链路开发体系
官方权威文档链接
- 微软中文官方教程（WSL 容器入门） https://learn.microsoft.com/zh-cn/windows/wsl/tutorials/wsl-containers
- 微软英文 WSL 容器核心说明页 https://learn.microsoft.com/en-us/windows/wsl/wsl-container
- GitHub WSL 2.9.3 Release（wslc 首发版本日志） https://newreleases.io/project/github/microsoft/WSL/release/2.9.3
第三方实操参考
- https://pureinfotech.com/install-wsl-containers-windows-11/
- https://allthings.how/install-wsl-containers-on-windows-11-with-wslc-public-preview/
一、概述：什么是 wslc
wslc.exe（别名container.exe）是微软内置在WSL 2.9.3+ 预发布版本的原生 Linux 容器 CLI 工具，官方命名 WSL Containers，2026 Build 大会发布公开预览版，无需额外安装 Docker Desktop、Podman 等第三方客户端，依托现有 WSL2 内核直接运行 OCI 标准容器镜像。
核心特性（客观复盘，无营销）
- 原生集成 Windows，仅更新 WSL 预发布内核即可启用，无独立安装包；
- CLI 语法高度兼容 Docker，原有容器命令迁移成本极低；
- 复用系统硬件虚拟化、WSLg 图形、CUDA 显卡直通能力，适配 AI、后端开发场景；
- 纯终端工具，无常驻后台 GUI 托盘进程，闲置资源占用更低；
- 隔离模型基于轻量 Hyper-V 虚拟机，容器间资源边界隔离更强。
适用 / 不适用场景
✅ 适合：本地轻量开发、临时数据库 / 中间件容器、AI 推理环境、不想安装重型容器客户端的用户 ❌ 不适合：需要完整 Compose、K8s、可视化面板、企业集群管理的生产环境
二、前置硬件 & 系统条件
- 硬件：CPU 开启 Intel VT-x / AMD-V 硬件虚拟化（BIOS/UEFI 设置）；
- 系统版本：Windows 10 2004+（Build 19041）、Windows 11 全版本；Windows 预览版（如本机 10.0.29617）兼容性最佳；
- 基础组件：已启用「适用于 Linux 的 Windows 子系统」「虚拟机平台」；未安装 WSL 需先执行
wsl --install； - 权限：所有更新、校验操作必须使用管理员终端（PowerShell 5/7、Windows Terminal 均可）。
三、完整安装启用流程（实操复盘，重点补充终端刷新细节）
步骤 1：更新 WSL 至预发布内核（唯一开启 wslc 的途径）
稳定版 WSL 不含 wslc 二进制文件，必须拉取预发布更新：
powershell
# 管理员终端执行 wsl --update --pre-release执行日志示例（本机实测）：
plaintext
正在检查更新。 正在更新适用于 Linux 的 Windows 子系统: 2.9.4。关键细节：更新后旧终端无法识别新命令
Windows 终端 / PowerShell 进程启动时一次性加载系统 PATH 与 System32 下可执行文件；更新内核后wslc.exe才写入C:\Windows\System32，已打开的旧终端不会自动刷新文件列表，直接输入wslc会抛出「无法识别命令」报错，这是绝大多数人踩坑的核心原因。
步骤 2：强制关闭全部 WSL 实例（可选，推荐）
powershell
wsl --shutdown作用：彻底释放正在运行的 WSL 内核进程，保证新版本内核完整加载。
步骤 3：重新新开新终端（推荐）
- 关闭所有已打开的 PowerShell/Windows Terminal 窗口；
- 右键开始菜单，重新打开一个新终端；
若不在新终端中测试，可能会出现在当前终端无法识别
wslc命令的报错。
步骤 4：校验 WSL 整体内核版本
确认版本≥2.9.3（wslc 最低支持基线）：
powershell
wsl --version本机输出参考：
plaintext
WSL 版本: 2.9.4.0 内核版本: 6.18.35.2-1 WSLg 版本: 1.0.79 MSRDC 版本: 1.2.7214 Direct3D 版本: 1.611.1-81528511 DXCore 版本: 10.0.26100.1-240331-1435.ge-release Windows 版本: 10.0.29617.1000步骤 5：校验 wslc 是否正常加载
新开管理员终端后执行：
powershell
# 两种等价写法 wslc version wslc --version正常返回：wslc 2.9.4.0
四、高频报错完整排查（重点标注终端刷新问题）
报错 1：wslc : 不是可识别cmdlet/程序
分层排查顺序（按优先级）
- 第一层（90% 场景）：未重启终端
- 诱因：更新
wsl --update --pre-release后仍使用更新前打开的旧终端； - 修复：关闭所有终端，重新以管理员身份新开窗口，再执行
wslc --version；
- 诱因：更新
- 第二层：仅执行 shutdown 但未重启终端
wsl --shutdown仅关闭 Linux 内核，不会刷新 Windows 终端的可执行文件缓存，必须重启终端进程； - 第三层：内核更新未完整部署
powershell
返回# 验证二进制文件是否存在 Test-Path C:\Windows\System32\wslc.exeFalse则重新执行预发布更新：powershell
wsl --update --pre-release - 第四层：重启电脑兜底新开终端仍失效时，重启整机完成系统组件注册。
报错 2：输入wsl --get-version提示无效参数
不存在该参数，查看 WSL 组件版本固定为wsl --version；查看本地 Linux 发行版列表使用wsl -l -v。
五、wslc 基础核心命令（兼容 Docker 标准语法）
1. 镜像管理（image）
powershell
# 拉取Docker Hub OCI镜像 wslc pull ubuntu wslc pull nginx # 列出本地镜像（两条等价） wslc image ls wslc images # 删除指定镜像 wslc image rm ubuntu # 清理无标签、未使用的冗余镜像 wslc image prune2. 容器生命周期管理
powershell
# 临时测试容器，退出自动销毁 wslc run --rm hello-world # 交互式进入Ubuntu容器终端 wslc run --rm -it ubuntu bash # 后台启动Nginx，端口映射Windows 8080:80，命名web wslc run -d --name web -p 8080:80 nginx # 查看运行中容器 wslc container ps wslc ps # 查看全部容器（含已停止） wslc ps -a # 启停指定命名容器 wslc stop web wslc start web # 删除停止的容器 wslc rm web # 一键清理所有已停止容器 wslc container prune3. 辅助运维命令
powershell
# 实时查看容器CPU/内存资源占用 wslc stats # 打印容器运行日志 wslc logs web # 登录私有镜像仓库 wslc registry login [仓库地址] # 查看完整官方帮助文档 wslc --help # 单命令详细参数说明 wslc run --help六、wslc、Docker Desktop、Podman 客观对比
表格
| 对比维度 | wslc(WSL Containers) | Docker Desktop | Podman(WSL) |
|---|---|---|---|
| 安装方式 | WSL 预发布内核更新，无独立程序 | 完整客户端安装包 | 单独下载安装 |
| 常驻后台进程 | 无守护程序，随容器启停 | 常驻 dockerd、托盘 GUI | 无根架构，无常驻守护 |
| 闲置资源占用 | 最低，复用现有 WSL2 内核 | 高，空闲占用 1GB+ | 中等 |
| 图形可视化界面 | 仅纯 CLI，无图形面板 | 完整可视化管理界面 | 可选第三方 GUI |
| 命令语法兼容 | 90% Docker 命令通用 | 原生 Docker 标准 | 100% 兼容 Docker 语法 |
| GPU/CUDA 支持 | 原生 WSL2 显卡直通，开箱即用 | 支持但需额外配置 | 原生支持 |
| 额外依赖 | 仅依赖已启用的 WSL2 | 内置独立 WSL/Hyper-V 虚拟机 | 依赖 WSL 或本地虚拟机 |
| 适用项目规模 | 本地单容器开发、临时服务、AI 测试 | 全场景，含 Compose、集群、CI 流水线 | 轻量本地开发、无根容器安全场景 |
七、实操踩坑复盘（含终端缓存坑完整说明）
- 终端缓存致命坑（本机实测首要问题）执行
wsl --update --pre-release后，旧终端进程缓存不会加载新增的wslc.exe，必须全部关闭终端再新开管理员窗口，否则持续报命令不存在；仅执行wsl --shutdown无法解决此问题； - 命令混淆坑
- WSL 系统组件版本：
wsl --version，不存在--get-version； - 容器工具：
wslc，不要误写 wslc.exe version（终端可省略 exe 后缀）；
- WSL 系统组件版本：
- 端口映射逻辑
-p 主机端口:容器端口规则与 Docker 完全一致，Windows 本地可直接curl localhost:端口访问容器内服务； - 多发行版共存不冲突本机同时存在 Ubuntu、podman-machine-default 等 WSL 发行版，wslc 使用独立容器运行时，不占用现有发行版资源、互不抢占内核；
- 预览版功能限制当前为公开预览阶段，暂不支持 Docker Compose、自定义复杂网桥网络、持久卷高级挂载，多容器联动复杂项目建议搭配 Podman/Docker Desktop 备用。
八、典型完整实操示例
示例 1：本地快速搭建 Nginx 网页服务
powershell
# 1. 拉取官方Nginx镜像 wslc pull nginx # 2. 后台启动容器，端口映射8080 wslc run -d --name demo-nginx -p 8080:80 nginx # 3. Windows浏览器访问：http://localhost:8080 # 4. 查看运行状态 wslc ps # 5. 停止并彻底清理容器 wslc stop demo-nginx wslc rm demo-nginx示例 2：交互式 Ubuntu 临时开发环境
powershell
# 拉取22.04稳定镜像 wslc pull ubuntu:22.04 # 进入交互式终端，退出容器自动销毁 wslc run --rm -it ubuntu:22.04 bash # 容器内可执行apt、Python、CUDA推理等开发操作九、总结与稳定使用建议
- wslc 是微软轻量化原生容器替代方案，核心优势：零额外软件安装、低资源消耗、原生兼容 WSL 显卡加速，适合开发人员快速拉起临时测试容器；
- 当前处于公开预览阶段，功能存在缺失，无 Compose、集群、可视化管理能力，生产环境 / 多容器编排项目不建议作为主力工具；
- 标准化稳定操作流程（规避终端缓存报错）： 管理员终端执行
wsl --update --pre-release→wsl --shutdown→关闭全部终端，重新新开管理员终端→wsl --version校验内核 →wslc --version校验容器工具； - 多工具共存方案：Windows 可同时保留传统 WSL 发行版、podman-machine、wslc 三套环境，三者内核运行层隔离，无资源冲突，可根据项目需求按需切换。
【笔记】切换 WSL 到 预览版