手把手：用Docker Compose搭建本地K8s开发环境（附避坑指南）

duckwolf

> 类型：实战教程 | 板块：云原生 | 日期：2026-03-29

---

每次说到本地K8s开发环境，大家第一反应都是 minikube 或者 kind。但这两个工具在 Windows 上经常有各种玄学问题。今天分享一套我在用的方案：Docker Compose 模拟 K8s 核心工作流，真正做到"本地开发0差异"。

---

为什么不直接用minikube？

| 工具 | 优点 | 痛点 |
|------|------|------|
| minikube | 接近真实K8s | 资源占用高、Windows兼容问题多 |
| kind | 轻量快速 | 网络配置复杂 |
| Docker Compose | 上手简单 | 不是真正K8s，需要手动对齐概念 |

结论：本地开发阶段，用 Docker Compose 开发+调试，CI环境用真实K8s验证。两者工作流保持一致就行。

---

环境准备

2. [b][size=6]确认 Docker Desktop 已安装并运行[/size][/b]
3. docker --version  # >= 24.0
4. docker compose version  # >= 2.20
7. [b][size=6]安装 kubectl（用于后续真实集群操作）[/size][/b]
8. winget install Kubernetes.kubectl  # Windows
9. brew install kubectl               # Mac

复制代码

---

项目结构

1. myapp/
2. ├── docker-compose.yml      # 本地开发环境
3. ├── docker-compose.prod.yml # 生产对齐配置
4. ├── services/
5. │   ├── api/
6. │   │   ├── Dockerfile
7. │   │   └── src/
8. │   └── worker/
9. │       ├── Dockerfile
10. │       └── src/
11. ├── nginx/
12. │   └── nginx.conf
13. └── scripts/
14.     └── init-db.sql

复制代码

---

核心 docker-compose.yml

1. version: '3.9'
3. services:
4.   # 网关层（对应 K8s Ingress）
5.   nginx:
6.     image: nginx:alpine
7.     ports:
8. • "80:80"
9.     volumes:
10. • ./nginx/nginx.conf:/etc/nginx/nginx.conf:ro
11.     depends_on:
12. • api
13.     networks:
14. • app-net
16.   # API服务（对应 K8s Deployment）
17.   api:
18.     build:
19.       context: ./services/api
20.       target: development          # 多阶段构建：开发阶段
21.     environment:
22. • NODE_ENV=development
23. • DB_HOST=postgres
24. • REDIS_HOST=redis
25.     volumes:
26. • ./services/api/src:/app/src  # 热重载
27.     restart: unless-stopped
28.     healthcheck:
29.       test: ["CMD", "curl", "-f", "http://localhost:3000/health"]
30.       interval: 30s
31.       timeout: 10s
32.       retries: 3
33.     networks:
34. • app-net
36.   # 异步Worker（对应 K8s Job/CronJob）
37.   worker:
38.     build:
39.       context: ./services/worker
40.     environment:
41. • REDIS_HOST=redis
42.     depends_on:
43. • redis
44.     networks:
45. • app-net
47.   # 数据库（对应 K8s StatefulSet）
48.   postgres:
49.     image: postgres:16-alpine
50.     environment:
51.       POSTGRES_DB: myapp
52.       POSTGRES_USER: dev
53.       POSTGRES_PASSWORD: devpassword
54.     volumes:
55. • postgres_data:/var/lib/postgresql/data
56. • ./scripts/init-db.sql:/docker-entrypoint-initdb.d/init.sql
57.     networks:
58. • app-net
60.   # 缓存
61.   redis:
62.     image: redis:7-alpine
63.     command: redis-server --appendonly yes
64.     volumes:
65. • redis_data:/data
66.     networks:
67. • app-net
69. volumes:
70.   postgres_data:
71.   redis_data:
73. networks:
74.   app-net:
75.     driver: bridge

复制代码

---

让本地=生产：关键配置对齐


1. 多阶段Dockerfile（开发/生产同一镜像）

2. [b][size=6]services/api/Dockerfile[/size][/b]
3. FROM node:20-alpine AS base
4. WORKDIR /app
5. COPY package*.json ./
6. RUN npm ci --only=production
8. FROM base AS development
9. RUN npm ci  # 包含devDependencies
10. COPY . .
11. CMD ["npm", "run", "dev"]  # 热重载模式
13. FROM base AS production
14. COPY . .
15. RUN npm run build
16. CMD ["node", "dist/index.js"]

复制代码

2. 环境变量管理（对应 K8s ConfigMap/Secret）

2. [b][size=6].env.local（不提交git）[/size][/b]
3. DB_HOST=postgres
4. DB_PASSWORD=devpassword
7. [b][size=6].env.example（提交git，供参考）[/size][/b]
8. DB_HOST=
9. DB_PASSWORD=

复制代码

---

常用命令速查

2. [b][size=6]启动所有服务[/size][/b]
3. docker compose up -d
6. [b][size=6]查看日志（类似 kubectl logs）[/size][/b]
7. docker compose logs -f api
10. [b][size=6]进入容器（类似 kubectl exec）[/size][/b]
11. docker compose exec api sh
14. [b][size=6]重建单个服务（代码变更后）[/size][/b]
15. docker compose up -d --build api
18. [b][size=6]清理环境[/size][/b]
19. docker compose down -v  # -v 同时删除volume

复制代码

---

踩坑记录

坑1：healthcheck 导致依赖服务启动失败  
症状：api 启动报错"连不上数据库"  
原因：

1. depends_on

复制代码

默认只等容器启动，不等服务 ready  
修复：

1. depends_on:
2.   postgres:
3.     condition: service_healthy  # 等healthcheck通过再启动

复制代码

坑2：Windows下volume热重载不生效  
原因：WSL2 文件系统事件通知机制差异  
修复：把项目放在

1. \\wsl$\Ubuntu\

复制代码

路径下，不要放在 Windows 盘符路径

坑3：网络命名冲突  
症状：第二个项目起不来，报网络已存在  
修复：给每个项目的网络加唯一前缀

1. networks:
2.   myapp-net:    # 用项目名前缀
3.     driver: bridge

复制代码

---

下一步

本地跑通后，把

1. docker-compose.yml

复制代码

的概念映射到真实 K8s：
•

1. service

复制代码

→

1. Deployment

复制代码

+

1. Service

复制代码

•

1. volumes

复制代码

→

1. PersistentVolumeClaim

复制代码

•

1. environment

复制代码

→

1. ConfigMap

复制代码

/

1. Secret

复制代码

•

1. healthcheck

复制代码

→

1. livenessProbe

复制代码

/

1. readinessProbe

复制代码

推荐工具：Kompose（自动把 docker-compose.yml 转成 K8s YAML）

1. kompose convert -f docker-compose.yml

复制代码

---

有什么问题或者补充的坑，欢迎评论区见