用 Docker Compose 一次跑起本地开发环境：思路、命令与新手避坑

很多新手第一次做本地开发，都会遇到同一个麻烦：前端要起一个服务，后端要起一个服务，数据库还要单独装一个，换一台电脑又要从头配一遍。Docker Compose 就是用来解决这个问题的：它用一个文件把多个服务写在一起，一条命令就能把它们按顺序启动、按名字互相访问，关掉时也能一起清理。理解它的思路，比背命令更重要。

先说一个最简单的场景。假设本地有一个静态页面、一个自己写的接口服务和一个数据库，我们希望它们能一起工作。传统做法是分别启动三个程序，再手动记端口和连接地址，任何一个端口被占用都会卡住。改用 Compose 之后，我们只需要准备一个目录，里面放一个 compose 文件和各自的代码，文件里写清楚每个服务用什么镜像或从哪里构建、对外暴露哪个端口、挂载哪个目录、依赖哪个服务。启动时，Compose 会按依赖关系创建网络和容器，让服务之间用服务名互相访问，而不是硬编码宿主机的地址。

一个常见的 compose 文件思路是这样的：web 服务负责提供页面，对外映射一个本地端口，并把本地的页面目录挂载进去，改页面不用重新构建；api 服务从本地代码构建，映射接口端口，并声明依赖数据库；db 服务使用数据库镜像，并通过环境变量设置本地开发用的账号和密码，数据目录挂载到具名卷里，避免容器删掉后数据跟着消失。需要注意的是，这里的密码只是本地示例，绝不能直接用到生产环境，真实项目应当使用更安全的配置方式。

日常最常用的命令并不多。第一次启动用 docker compose up -d，让服务在后台运行；查看状态用 docker compose ps，查看某个服务的日志用 docker compose logs -f 服务名；改完代码后，如果是挂载目录里的页面或脚本，通常直接刷新就能看到效果，如果改的是构建阶段的内容，就需要重新构建再启动；全部停掉用 docker compose down，需要连数据卷一起清理时才加上 -v，否则不要轻易加这个参数。进入容器排错可以用 docker compose exec 服务名 sh，但这只是临时手段，真正的问题还是要回到配置文件和代码里修。

新手最容易踩的坑有四个。第一是端口冲突：本地端口已经被别的程序占用时，容器会启动失败，先换一个本地端口或停掉占用程序，再重新启动。第二是路径问题：挂载目录要用相对于 compose 文件的路径，写绝对路径换电脑就容易失效。第三是把容器里的 localhost 当成宿主机：服务之间互相访问要用服务名，只有从宿主机浏览器访问时才用 localhost 加映射端口。第四是数据丢失：用 docker compose down -v 会删除具名卷，开发数据库里的重要测试数据可能就此消失，清理前一定要先确认。

最后给一个收尾清单：先确认每个服务的端口、挂载目录和依赖关系都写清楚；再用一条命令启动并逐个看日志，确认没有报错；最后记下启动、查看日志、停止这三个命令，下次换电脑只要带走代码和 compose 文件，就能快速恢复同样的开发环境。把环境写进文件，本身就是一种文档，比口头交接可靠得多。