wslc — WSL 容器 CLI

wslc（Windows Subsystem for Linux 容器 CLI，版本 2.9.x）是 WSL 自带的容器管理工具，命令行风格与 docker 兼容。二进制位于 C:\Program Files\WSL\wslc，通常已加入 PATH。支持 Linux 容器，无需安装 Docker Desktop。

何时使用

用户要求用本机 Windows 环境跑/管理容器（生命周期、镜像、端口、卷、网络、构建、日志等）时优先使用本技能。凡涉及容器操作，先走下面的核心工作流。

快速开始

# 拉取镜像
wslc pull nginx

# 前台运行（默认）
wslc run nginx

# 后台运行 + 命名 + 端口映射
wslc run -d --name web -p 8080:80 nginx

# 交互式进入（TTY + Stdin）
wslc run -it --rm --name shell ubuntu bash

# 查看运行中的容器
wslc list

# 在运行中的容器里执行命令
wslc exec web ls /usr/share/nginx/html

# 查看日志（跟随）
wslc logs -f web

# 停止 / 删除
wslc stop web
wslc rm web

⚠️ 关键注意事项

Git Bash 会改写容器内路径（最常见坑）

在 Git Bash（MSYS）下运行 wslc exec、-v 等传容器内 / 开头的路径时，MSYS 会自动把 /usr/share/nginx/html 转成 Windows 路径 C:/local/Git/usr/share/nginx/html，导致命令失败。两种解决办法：

# 方法一：禁用路径转换（推荐）
MSYS_NO_PATHCONV=1 wslc exec web ls /usr/share/nginx/html

# 方法二：双斜杠前缀，绕过转换
wslc exec web ls //usr/share/nginx/html

卷挂载也一样：-v 的 <主机>:<容器> 两侧路径都可能被转换，必要时加 MSYS_NO_PATHCONV=1。

命令别名与差异

list 的别名：ls、ps；remove 的别名：rm、delete。
顶层没有 cp —— 复制文件用 wslc container cp <容器>:<路径> <本地路径>。
顶层没有 prune —— 清理用 wslc container prune、wslc network prune、wslc volume prune。
run 不支持 --restart；无 --platform。别写 docker 里有的、wslc 没有的选项（用 wslc <cmd> --help 确认）。

run 常用选项（与选项实际集一致）

| 选项 | 说明 | |------|------| | -d, --detach | 后台运行（默认前台） | | -i, --interactive / -t, --tty | 交互 Stdin / 打开 TTY，合写 -it | | --name | 容器命名（之后可用名字替代 ID） | | -p, --publish | 端口映射 主机:容器 或 IP:主机:容器，如 -p 8080:80 | | -P, --publish-all | 全部暴露端口映射到随机主机端口 | | -v, --volume | 挂载卷/绑定目录 主机路径:容器路径[:ro] | | -e, --env | 环境变量 KEY=VALUE（可重复） | | --env-file | 从文件读取环境变量，每行 KEY=VALUE | | --rm | 容器停止后自动删除（临时代理想用） | | -m, --memory | 内存限制，如 512M、1G | | --cpus | CPU 数限制，如 0.5、1、2.5 | | -u, --user | 指定用户 name|xuid|uid:gid | | -w, --workdir | 容器内工作目录 | | -h, --hostname | 容器主机名 | | --entrypoint | 覆盖启动命令 | | --dns / --dns-search | DNS 配置 | | --tmpfs | 挂载 tmpfs 到指定路径 | | --shm-size | /dev/shm 大小，如 64M、1G | | --gpus | 传入 GPU 设备（all 传全部） | | --health-cmd 等 --health-* | 健康检查配置（--no-healthcheck 禁用） | | --ulimit | ulimit 选项 名称=软[:硬]，-1 不限 | | --stop-timeout / --stop-signal | 停止超时(秒) / 停止信号 | | --cidfile | 把容器 ID 写入指定文件 |

生命周期工作流

拉镜像：wslc pull <镜像>（现有本地镜像可用 wslc images 查看）
运行：wslc run -d --name <名> [<选项>] <镜像> [<命令>] [<参数>]
查看状态：wslc list -a（-a 含已停止）、wslc stats（资源占用）
进入/执行：wslc exec -it <名> bash；wslc attach <名>（附加主进程）
看日志：wslc logs [-f] [-n <行数>] [--timestamps] <名>
停止与重启：wslc stop <名>（默认等 5 秒，-t <秒> 调整）、wslc start <名>、wslc kill（强杀，可 -s <信号>）
删除：wslc rm [-f] <名>；清理所有已停止容器 wslc container prune

常用场景示例

# 临时起一个 Ubuntu 交互 shell（退出即删）
MSYS_NO_PATHCONV=1 wslc run -it --rm ubuntu bash

# 起 nginx 并映射端口，不动宿主目录
wslc run -d --name web -p 8080:80 nginx

# 起 postgres，持久化数据目录 + 环境变量
MSYS_NO_PATHCONV=1 wslc run -d --name pg \
  -e POSTGRES_PASSWORD=secret \
  -p 5432:5432 \
  -v /d/data/pg:/var/lib/postgresql/data \
  postgres:17

# 起一个受限资源的服务
wslc run -d --name api -p 9000:9000 -m 512M --cpus 1 myimage:latest

镜像操作

wslc images                 # 列出本地镜像
wslc images --format json   # JSON 输出
wslc pull <镜像>             # 拉取官方/自定义镜像
wslc push <镜像>             # 推送（需先 wslc login）
wslc tag <源> <目标>         # 打标签
wslc rmi [-f] <镜像>         # 删除镜像（-f 强制，含在使用中的）
wslc rmi <镜像> --no-prune   # 保留未标记父镜像

构建与迁移：

# 该目录下放 Dockerfile，构建并打标签
wslc build -t myapp:v1 .

# 自定义 Dockerfile / 目标阶段 / 构建参数
wslc build -f path/to/Dockerfile --target prod --build-arg VERSION=1 --no-cache -t myapp:v1 .

wslc save <镜像> | gzip > img.tar.gz   # 导出镜像
wslc load < img.tar.gz                 # 导入镜像
wslc export <容器> > fs.tar            # 导出容器文件系统
wslc import fs.tar <镜像>               # 从 tarball 导入

数据持久化（卷）

wslc volume create mydata       # 具名卷
wslc volume list
wslc volume inspect mydata
wslc volume prune               # 清理未使用卷

# 容器挂载具名卷
wslc run -d -v mydata:/var/lib/mysql --name db mysql:8

网络

wslc network list
wslc network create mynet
wslc network connect mynet <容器>
wslc network disconnect mynet <容器>
wslc network inspect mynet
wslc network prune

# 容器加入自定义网络
wslc run -d --name svc --network mynet myimage

登录 / 注册表凭据

wslc login <registry>        # 交互输入用户名密码
wslc logout <registry>
wslc registry --help         # 管理存储的凭据

其它常用命令

wslc version                          # 版本信息
wslc settings                         # 在默认编辑器打开设置文件
wslc inspect [-t <type>] <name|id>    # 检查任意对象细节
wslc container cp <名>:<容器内路径> <本地路径>   # 复制文件（注意顶层没有 cp）

排障

ls: cannot access 'C:/local/Git/...' 或路径带 <dir> 前缀 → MSYS 路径转换，加 MSYS_NO_PATHCONV=1 或用 // 前缀。
无法识别的命令/Unable to find image → 检查顶层命令拼写（wslc cp --help 会失败，正确是 wslc container cp）；确认镜像名/标签存在。
端口占用：wslc run -p 8080:80 ... 报端口冲突，换端口或先 wslc list 看端口占用。
前台运行卡住 → 那是 run 默认前台行为，用 -d 后台、或 Ctrl+C 停止（前台容器会随终端退出）。
对某个命令不确定时，先 wslc <命令> --help 看真实可用的选项，别照搬 docker 文档。