WSL2 Ubuntu 配置完美版 docker compose 指南

WSL2 Ubuntu 配置 docker compose 指南

📌 背景与痛点

• 命令演变 ：早期的 Docker Compose 是一个独立工具（docker-compose），而现代 Docker 已将其重构为 Docker CLI 的内置插件（docker compose，带空格）。

• WSL2 的坑 ：Docker Desktop 在向 WSL2 同步命令时，有时只同步了独立的可执行文件，导致在 Ubuntu 中使用新版 docker compose 时失效，或报错提示缺少 buildx 插件：

  WARN[0000] Docker Compose requires buildx plugin to be installed

🛠️ 终极解决方案：安装官方 CLI 插件并配置软链接

通过在 Ubuntu 内部安装官方的 Docker 客户端及插件，并将其软链接到用户目录，可以一劳永逸地解决空格命令失效 与 buildx 警告的问题。（注：此操作仅安装客户端，不会影响 Windows 上已有的 Docker 镜像和数据）。

第一步：在 Ubuntu 中安装 Docker CLI 及插件

依次在 WSL2 Ubuntu 终端中运行以下命令：

1. 更新 apt 索引并安装基础依赖

Bash

sudo apt-get update
sudo apt-get install -y ca-certificates curl gnupg

2. 添加 Docker 官方的 GPG 密钥

Bash

sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg

3. 设置 Docker 的官方软件源仓库

Bash

echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \
  $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

4. 安装 Docker 客户端、Compose 插件及 Buildx 插件

Bash

sudo apt-get update
sudo apt-get install -y docker-ce-cli docker-compose-plugin docker-buildx-plugin

第二步：配置插件软链接（核心打通）

由于 WSL2 默认可能会优先调用 Windows 传递过来的 docker 客户端，我们需要在当前用户的配置目录下建立软链接，让 Docker 能够精准识别到刚刚安装的正版插件。

Bash

# 1. 确保当前用户的插件目录存在
mkdir -p ~/.docker/cli-plugins

# 2. 将 Ubuntu 正版的 compose 插件链接过去
ln -s /usr/libexec/docker/cli-plugins/docker-compose ~/.docker/cli-plugins/docker-compose

# 3. 将 Ubuntu 正版的 buildx 插件也链接过去（彻底消灭 Warn 警告）
ln -s /usr/libexec/docker/cli-plugins/docker-buildx ~/.docker/cli-plugins/docker-buildx

第三步：验证结果

运行以下命令检查，此时不仅可以使用带空格的 docker compose，且无任何报错或警告：

Bash

docker compose version