Docker Compose 入门：用一份 YAML 文件拉起完整的本地开发环境

本地开发环境搭建，是一件“说起来简单、做起来糟心”的事。装 MySQL 要配字符集，装 Redis 要改端口，Python 项目还要处理虚拟环境和依赖版本冲突。换一台电脑，这些步骤又得重来一遍，还常常卡在“在我机器上明明是好的”这种玄学问题上。

Docker 把“一次构建、到处运行”变成了现实，而 Docker Compose 则更进一步：用一份 YAML 文件，把多个容器的启动、组网、数据持久化全部描述清楚。今天这篇短文，就带你从零写出第一份 docker-compose.yml。

一、Docker Compose 是什么

一句话概括：Docker Compose 是 Docker 官方的多容器编排工具，用一份 YAML 文件定义应用包含哪些服务、如何组网、数据存在哪，然后一条命令全部拉起。现在它已经作为 docker compose 子命令内置，不再需要单独安装。

二、安装与验证

Windows / macOS 安装 Docker Desktop 即自带 Compose；Linux 服务器上安装 Docker Engine 后，再安装 compose 插件。安装完成后执行：

docker compose version

能看到版本号，就说明环境就绪。

三、写第一份 docker-compose.yml

假设我们有一个简单的 Python Flask 应用，需要搭配 Redis 做缓存。目录结构如下：

myapp/
  docker-compose.yml
  app/
    Dockerfile
    app.py

docker-compose.yml 内容：

services:
  web:
    build: ./app
    ports:
      - "5000:5000"
    environment:
      - REDIS_HOST=redis
    depends_on:
      - redis
  redis:
    image: redis:7-alpine
    volumes:
      - redis-data:/data

volumes:
  redis-data:

逐行解释：services 下面每个键就是一个服务；web 服务用 build 从本地 Dockerfile 构建，ports 把容器的 5000 端口映射到宿主机；environment 注入环境变量，让应用知道 Redis 的主机名就叫 redis——Compose 会自动为这些服务创建同一个网络，服务名即主机名；redis 服务直接用官方镜像，volumes 把数据目录挂到命名卷 redis-data，这样容器删掉数据还在。

四、四个常用命令

在 myapp 目录下执行 docker compose up -d，后台拉起所有服务。docker compose ps 查看运行状态，docker compose logs -f web 实时看日志。做完实验想清理：docker compose down 停止并删除容器和网络，加上 -v 还会删除命名卷。

五、三个实战小技巧

第一，敏感信息别写进 yml。数据库密码这类变量放到同目录的 .env 文件里，Compose 会自动读取，既安全又方便区分开发、测试环境。

第二，depends_on 只保证启动顺序，不保证“服务就绪”。如果应用启动时 Redis 还没准备好，连接会失败。稳妥的做法是给 redis 加 healthcheck，或在应用里做重试。

第三，开发阶段善用 volumes 挂载。把本地代码目录挂进容器，改完代码不用重新构建镜像就能生效，调试效率翻倍。

六、一个新手最容易踩的坑：端口冲突

如果宿主机的 5000 端口已经被占用，容器会启动失败。改法很简单，只改冒号左边的宿主机端口，比如 "5001:5000"，容器内部不用动。

结语

从今天开始，试着把团队里那份“环境搭建文档”换成一份 docker-compose.yml。新人入职只需要两步：git clone，docker compose up -d。五分钟，就能进入开发状态——这才是本地环境该有的样子。