Docker Compose 一键搭起本地开发环境：一次写好，到处能跑

本地开发最常见的浪费，不是写代码，而是搭环境：同事机器上能跑，自己的机器上数据库连不上；换一台电脑，又要重装依赖、重配端口。Docker Compose 就是为此而生的：把应用、数据库、缓存写进一个 docker-compose.yml，一条命令拉起整套环境，而且每个人的环境都来自同一份定义。

docker-compose.yml 的基本结构

Compose 的核心是 services，每个服务对应一个容器。常用字段只有几个：image 指定镜像，build 用本地 Dockerfile 构建，ports 做端口映射，environment 注入环境变量，volumes 挂载数据卷，depends_on 声明启动依赖。读懂这几个字段，就能读懂绝大多数 Compose 文件。

services:
  web:
    build: .
    ports: ["3000:3000"]
    environment:
      - DATABASE_URL=postgres://dev:dev@db:5432/appdb
    volumes: [.:/app]
    depends_on: [db, cache]
  db:
    image: postgres:16
    volumes: [pgdata:/var/lib/postgresql/data]
  cache:
    image: redis:7
volumes: { pgdata: {} }

服务之间用服务名互访，web 用 db 当数据库主机名，不用写 localhost；端口写成“宿主机端口:容器端口”；命名卷 pgdata 让数据库数据在容器删除后依然保留。

常用命令

docker compose up -d 后台启动全部服务；docker compose ps 查看服务状态；docker compose logs -f web 实时看某个服务的日志，排障最常用；docker compose down 停止并删除容器和网络，默认保留数据卷；docker compose down -v 则连数据卷一起删，只在确实想清空数据时用。改解释型代码配合目录挂载一般不用重启，改 Dockerfile 或依赖才需重新构建。

多服务编排与数据卷

编排的关键是职责分清：应用管业务，数据库管存储，缓存管加速。服务间走内部网络，对外只暴露真正需要的端口，例如只暴露应用端口，不把数据库端口映射到宿主机，既安全又少端口冲突。数据卷分两种：命名卷适合数据库这类需持久化、无需直接编辑的数据；绑定挂载适合把本地代码目录挂进容器，改代码即生效。两者常配合使用。

一个实用的开发环境示例

做前后端分离项目时，Compose 里放前端、后端、Postgres 和 Redis 四个服务：前端走 5173，后端走 3000，数据库和缓存只在内部网络可见。新同事不用再按文档一步步装数据库和缓存，装好 Docker 后执行 docker compose up -d，用 ps 确认状态即可开工；调试看 logs -f，收尾用 down，干净利落。

容易踩的坑

一是镜像写固定标签，如 postgres:16，别长期用 latest，否则不同时间拉到的版本可能不一致；二是密码密钥别写进文件提交仓库，改用 .env 注入；三是端口占用先查旧容器是否还在运行；四是 depends_on 只保证启动顺序，不保证数据库已就绪，应用最好自带重连或健康检查。一次写好，到处能跑，这正是本地开发最值得做的一次性投入。