Docker + Docker Compose 开发环境从零搭建指南

> 容器化是现代开发流程的基石。Docker 让「一次构建，到处运行」从口号变成现实，而 Docker Compose 则让多服务编排变得轻而易举。本文将从零开始，带你完成 Docker 开发环境的完整搭建。

## 为什么选择 Docker

传统开发环境中，依赖冲突、环境不一致、部署困难是三大痛点。Docker 通过容器化技术，将应用及其依赖打包成一个可移植的单元，彻底解决「在我机器上能跑」的问题。

核心优势：

- **环境一致性**：开发、测试、生产环境完全一致
- **快速启动**：秒级启动容器，无需漫长安装
- **资源隔离**：每个容器独立运行，互不干扰
- **版本管理**：镜像分层存储，方便回滚和分发

![Docker 架构图](https://mrdoc.wangziheng.vip/media/202605/2026-05-17_000710_2541970.5604639953813559.png)

## 安装 Docker Engine

### Ubuntu/Debian 系统

首先卸载旧版本：

```bash
sudo apt-get remove docker docker-engine docker.io containerd runc
```

安装必要依赖：

```bash
sudo apt-get update
sudo apt-get install ca-certificates curl gnupg
```

添加 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
```

添加仓库源：

```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
```

安装 Docker Engine：

```bash
sudo apt-get update
sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
```

### CentOS/RHEL 系统

```bash
sudo yum install -y yum-utils
sudo yum-config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo
sudo yum install docker-ce docker-ce-cli containerd.io docker-compose-plugin
```

### macOS 系统

推荐使用 Docker Desktop，从官网下载安装包即可：

```bash
brew install --cask docker
```

![终端安装演示](https://mrdoc.wangziheng.vip/media/202605/2026-05-17_000711_2623260.9945920078439835.png)

## 安装后配置

### 将用户加入 Docker 组

避免每次使用 `sudo`：

```bash
sudo usermod -aG docker $USER
newgrp docker
```

### 配置镜像加速

国内网络环境下，配置镜像加速器能显著提升拉取速度：

```bash
sudo mkdir -p /etc/docker
sudo tee /etc/docker/daemon.json <<EOF
{
  "registry-mirrors": [
    "https://mirror.ccs.tencentyun.com",
    "https://registry.docker-cn.com"
  ]
}
EOF
sudo systemctl daemon-reload
sudo systemctl restart docker
```

### 验证安装

```bash
docker --version
docker compose version
docker run hello-world
```

## Docker 基础操作速查

### 镜像管理

```bash
# 拉取镜像
docker pull nginx:latest
docker pull python:3.12-slim

# 查看本地镜像
docker images

# 删除镜像
docker rmi nginx:latest

# 构建镜像
docker build -t myapp:v1 .
```

### 容器管理

```bash
# 运行容器
docker run -d --name my-nginx -p 8080:80 nginx

# 查看运行中的容器
docker ps

# 查看所有容器（含停止的）
docker ps -a

# 进入容器
docker exec -it my-nginx /bin/bash

# 停止/启动/重启
docker stop my-nginx
docker start my-nginx
docker restart my-nginx

# 查看日志
docker logs -f my-nginx

# 删除容器
docker rm my-nginx
```

### 数据卷与网络

```bash
# 创建数据卷
docker volume create app-data

# 挂载数据卷
docker run -d -v app-data:/data myapp

# 创建自定义网络
docker network create app-net

# 容器加入网络
docker run -d --network app-net --name api myapi
```

## Docker Compose 多服务编排

当项目涉及多个服务（Web、API、数据库、缓存等），手动管理容器变得繁琐。Docker Compose 用一个 YAML 文件定义所有服务，一条命令启动全套环境。

![Docker Compose 编排流程](https://mrdoc.wangziheng.vip/media/202605/2026-05-17_000711_7116670.6199422899877164.png)

### 典型 Web 项目示例

创建 `docker-compose.yml`：

```yaml
services:
  web:
    image: nginx:alpine
    ports:
      - "8080:80"
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf
      - ./dist:/usr/share/nginx/html
    depends_on:
      - api
    networks:
      - app-net

api:
    build:
      context: ./api
      dockerfile: Dockerfile
    ports:
      - "3000:3000"
    environment:
      - DB_HOST=db
      - DB_PORT=3306
      - REDIS_URL=redis://cache:6379
    depends_on:
      db:
        condition: service_healthy
      cache:
        condition: service_started
    networks:
      - app-net

db:
    image: mysql:8.0
    environment:
      MYSQL_ROOT_PASSWORD: rootpass
      MYSQL_DATABASE: appdb
    volumes:
      - db-data:/var/lib/mysql
    ports:
      - "3306:3306"
    healthcheck:
      test: ["CMD", "mysqladmin", "ping", "-h", "localhost"]
      interval: 10s
      timeout: 5s
      retries: 5
    networks:
      - app-net

cache:
    image: redis:7-alpine
    ports:
      - "6379:6379"
    networks:
      - app-net

volumes:
  db-data:

networks:
  app-net:
    driver: bridge
```

### 常用 Compose 命令

```bash
# 启动所有服务（后台）
docker compose up -d

# 查看服务状态
docker compose ps

# 查看日志
docker compose logs -f api

# 重新构建并启动
docker compose up -d --build

# 停止所有服务
docker compose down

# 停止并删除数据卷
docker compose down -v

# 扩容（启动多个实例）
docker compose up -d --scale api=3
```

## 编写高效 Dockerfile

Dockerfile 是构建镜像的蓝图，写好它能大幅提升构建速度和镜像体积：

```dockerfile
# 多阶段构建示例 - Node.js 应用
FROM node:20-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY . .
RUN npm run build

FROM node:20-alpine
WORKDIR /app
COPY --from=builder /app/dist ./dist
COPY --from=builder /app/node_modules ./node_modules
EXPOSE 3000
CMD ["node", "dist/main.js"]
```

### Dockerfile 最佳实践

1. **使用 Alpine 基础镜像**：体积小、安全面小
2. **利用构建缓存**：先 COPY 依赖文件，再 COPY 源码
3. **多阶段构建**：编译阶段和运行阶段分离
4. **`.dockerignore` 排除无关文件**：减少构建上下文大小
5. **非 root 用户运行**：`USER appuser` 提升安全性

创建 `.dockerignore`：

```
node_modules
.git
.env
*.md
.vscode
```

## 开发环境进阶技巧

### 热重载开发

挂载源码目录实现实时热重载：

```yaml
services:
  dev:
    build: .
    volumes:
      - ./src:/app/src    # 挂载源码
    command: npm run dev   # 使用开发模式启动
```

### 环境变量管理

使用 `.env` 文件管理环境变量：

```bash
# .env
DB_PASSWORD=mysecretpass
API_PORT=3000
NODE_ENV=development
```

在 `docker-compose.yml` 中引用：

```yaml
services:
  api:
    environment:
      - DB_PASSWORD=${DB_PASSWORD}
      - API_PORT=${API_PORT}
    env_file:
      - .env
```

### 调试技巧

```bash
# 查看容器内进程
docker top my-nginx

# 查看容器资源占用
docker stats

# 导出容器文件系统
docker export my-nginx > nginx.tar

# 查看镜像构建历史
docker history nginx:alpine
```

## 常见问题排查

| 问题 | 解决方案 |
|------|----------|
| `permission denied` | 将用户加入 docker 组：`sudo usermod -aG docker $USER` |
| 端口冲突 | 修改映射端口或停止占用端口的进程 |
| 镜像拉取超时 | 配置镜像加速器或使用代理 |
| 容器无法通信 | 检查是否在同一网络：`docker network inspect app-net` |
| 数据丢失 | 使用数据卷持久化：`-v app-data:/data` |
| 构建缓存失效 | 检查 Dockerfile 指令顺序，将变化少的放前面 |

## 清理与维护

```bash
# 清理无用的镜像、容器、网络
docker system prune

# 包含未使用的镜像
docker system prune -a

# 清理未使用的数据卷
docker volume prune

# 查看 Docker 磁盘占用
docker system df
```

---

> Docker 的学习曲线并不陡峭，但收益巨大。从单容器运行到多服务编排，Docker + Docker Compose 的组合足以覆盖绝大多数开发场景。建议从一个简单的 `docker-compose.yml` 开始，逐步添加服务，在实践中加深理解。容器化的世界，等你来探索。