直接用 docker-compose up 启动本地镜像的前提是：docker-compose.yml 中 image 字段必须精确匹配 docker images 列出的镜像名和标签，且不能存在 build 块（否则会强制构建）；windows 下还需注意 wsl2 镜像同步状态。
直接用 docker-compose up 就能启动本地镜像，前提是镜像名在 docker images 里能查到，且 docker-compose.yml 中没写 build: 或已显式禁用构建逻辑。
docker-compose.yml 里 image 字段必须匹配本地镜像名和标签
这是最常踩的坑：你执行了 docker build -t myapp:dev .，但 docker-compose.yml 写的是 image: myapp 或 image: myapp:latest —— 如果构建时没打 :latest 标签，Docker Compose 就找不到镜像。
- 运行
docker images确认输出里有完整匹配项，比如myapp dev，那就必须写image: myapp:dev - 如果只写了
image: myapp，Docker 默认补:latest，但本地镜像未必有这个 tag -
image:和build:不能共存于同一服务；若同时存在，Compose 会忽略image:并强制构建
别让 build: 段落偷偷触发重建
很多教程模板默认保留 build: 配置，哪怕你只想用现成镜像。只要 build: 存在（哪怕只是空对象），docker-compose up 就会尝试构建，覆盖你手动构建好的镜像。
- 彻底删掉
build:块，或注释掉整段 - 如果必须保留构建能力（例如开发/测试切换），改用
docker-compose up --no-deps --no-build强制跳过构建 - 检查
docker-compose.yml是否被其他工具（如 VS Code Dev Container 插件）自动注入build:
Windows 下 Docker Desktop 的 WSL2 镜像缓存问题
Docker Desktop 在 Windows 上通过 WSL2 运行，镜像实际存在 WSL2 的 distro 文件系统中。有时你在 PowerShell 里 docker build 成功，但 docker-compose up 报 “image not found”，其实是 WSL2 实例未同步或挂起。
- 执行
wsl -l -v查看docker-desktop-data状态，确保是Running - 重启 WSL2：
wsl --shutdown，再打开 Docker Desktop - 避免在 Windows 文件资源管理器中直接操作 WSL2 内部路径（如
\wsl$docker-desktop-data…），可能破坏镜像元数据
真正卡住的地方往往不是语法，而是镜像名大小写、WSL2 状态、或者某个隐藏的 build: 配置在作祟。每次 docker-compose up 失败前，先跑一遍 docker images | findstr "your-image-name"（Windows）或 docker images | grep your-image-name（macOS/Linux），确认镜像真的“看得见”。
