文章目录
- 前言
- [一、为什么选择 docker-compose.yml？](#一、为什么选择 docker-compose.yml？)
- 二、前置准备
-
- [2.1 环境要求](#2.1 环境要求)
- [2.2 服务器 Docker 配置（必做）](#2.2 服务器 Docker 配置（必做）)
- [2.3 IDEA 配置远程 Docker 连接](#2.3 IDEA 配置远程 Docker 连接)
- 三、项目结构（标准前端部署架构）
- 四、核心配置编写（直接复制，一键可用）
-
- [4.1 编写 Dockerfile（基础镜像构建）](#4.1 编写 Dockerfile（基础镜像构建）)
-
- [4.2 编写 docker-compose.yml（核心编排配置）](#4.2 编写 docker-compose.yml（核心编排配置）)
-
- [五、IDEA 一键部署（可视化操作，零命令行）](#五、IDEA 一键部署（可视化操作，零命令行）)
-
- [5.1 运行配置](#5.1 运行配置)
- [5.2 部署流程（IDEA 自动完成）](#5.2 部署流程（IDEA 自动完成）)
- [5.3 访问验证](#5.3 访问验证)
- 六、进阶操作（日常部署必备）
-
- [6.1 切换分支部署（核心优势）](#6.1 切换分支部署（核心优势）)
- [6.2 查看容器日志](#6.2 查看容器日志)
- [6.3 停止/重启容器](#6.3 停止/重启容器)
- [6.4 版本升级（规范管理）](#6.4 版本升级（规范管理）)
- 七、常见问题及解决方案（避坑指南）
-
- [7.1 报错：invalid volume specification](#7.1 报错：invalid volume specification)
- [7.2 容器启动后立即退出](#7.2 容器启动后立即退出)
- [7.3 报错：client version 1.52 is too new. Maximum supported API version is 1.40](#7.3 报错：client version 1.52 is too new. Maximum supported API version is 1.40)
- [7.4 推送镜像失败：权限不足/连接超时](#7.4 推送镜像失败：权限不足/连接超时)
- 八、总结
- 附：完整配置文件汇总
-
- [1. docker/Dockerfile](#1. docker/Dockerfile)
- [2. docker/docker-compose.yml](#2. docker/docker-compose.yml)
前言
前端项目部署最怕什么？多分支切换反复改配置、端口冲突、容器名混乱、部署流程不统一。
之前我们用 WebStorm + Docker 插件实现了「本地编码→一键部署」，但切换分支时仍需手动调整镜像名、端口、容器名等参数，效率极低。WebStorm 借助 Docker 插件一键部署前端项目到开发环境
今天升级为 IDEA + docker-compose.yml 方案，彻底解决以上痛点！通过一个配置文件，实现镜像构建、版本管理、端口映射、容器命名全统一，切换分支只需一键运行，真正做到"一次配置，到处运行"。
一、为什么选择 docker-compose.yml？
docker-compose 是 Docker 官方推出的多容器编排工具 ，核心价值在于配置即代码，完美适配前端团队多分支、多环境的部署需求：
| 传统 Docker 部署（docker run） |
docker-compose 部署 |
| 配置分散在 IDE 本地，切换分支需重新配置 |
配置写在 yml 文件，提交 Git，全员共享，分支切换无需改动 |
| 镜像名、端口、容器名易混淆、漏配 |
固定配置，版本可控，一目了然 |
| 无法一键"构建+重启+运行" |
一键执行构建、推送、启动、停止，全流程可视化 |
| 多服务联动（如 Nginx+Java）配置复杂 |
天然支持多服务协同，扩展简单 |
一句话总结：docker-compose 是前端部署的"配置管家"，让部署更稳定、更高效、更易维护。
二、前置准备
2.1 环境要求
- 本地：IDEA 2021+（已安装 Docker 插件）、Docker Desktop
- 开发服务器：已开启 Docker 远程访问，开放 2375 端口
- 项目：已完成前端打包（
dist 目录）、准备好 Nginx 配置（nginx.conf）
2.2 服务器 Docker 配置（必做）
WebStorm 借助 Docker 插件一键部署前端项目到开发环境\]已配置，这里简要说明(https://blog.csdn.net/zhanghuaiyu_35/article/details/151999803?spm=1001.2014.3001.5501)
登录开发服务器 ，修改 Docker 配置，允许远程连接：
1. 编辑配置文件：
```bash
sudo vim /etc/docker/daemon.json
```
2. 添加内容（开放 TCP 连接）：
```json
{
"hosts": ["tcp://0.0.0.0:2375", "unix:///var/run/docker.sock"],
"log-driver": "json-file",
"log-opts": {
"max-size": "10m",
"max-file": "3"
}
}
```
3. 重启 Docker 生效：
```bash
sudo systemctl daemon-reload
sudo systemctl restart docker
```
### 2.3 IDEA 配置远程 Docker 连接
1. 打开 IDEA → 右上角 **Docker** 配置 → 新建连接
2. 选择 **TCP socket** ，输入：`tcp://服务器ip:2375`
3. 点击 **Test connection**，显示"Connection successful"即配置成功
> 注意：生产环境务必配置 TLS 加密访问，避免安全风险，开发环境可临时使用。
*** ** * ** ***
## 三、项目结构（标准前端部署架构）
先明确项目目录结构，避免后续路径配置出错：
项目根目录/
├── dist/ # 前端打包产物（已打包好的 HTML/CSS/JS）
├── docker/ # Docker 相关配置目录
│ ├── Dockerfile # 镜像构建文件
│ ├── nginx.conf # Nginx 核心配置（监听端口、路由等）
│ └── docker-compose.yml # 编排配置（核心）
└── ...（其他项目文件）
*** ** * ** ***
## 四、核心配置编写（直接复制，一键可用）
### 4.1 编写 Dockerfile（基础镜像构建）
路径：`docker/Dockerfile`
作用：基于 Nginx 镜像，打包前端代码和 Nginx 配置，生成专属镜像。
```dockerfile
# 基于 Alpine 版本 Nginx（轻量、安全）
FROM nginx:alpine
# 维护者信息
MAINTAINER huaiyu.zhang
# 覆盖 Nginx 配置（将宿主机 docker 目录下的 nginx.conf 复制到容器内）
ADD docker/nginx.conf /etc/nginx/nginx.conf
# 复制前端打包产物（将项目根目录的 dist 复制到 Nginx 静态文件目录）
COPY dist/ /usr/share/nginx/html/
# 关键：前台启动 Nginx（容器必须有前台进程，否则启动后会立即退出）
ENTRYPOINT ["nginx", "-g", "daemon off;"]
```
#### 关键说明
* `FROM nginx:alpine`：选择轻量版 Nginx，镜像体积小，部署更快
* `ADD/COPY`：注意路径对应项目结构，`docker/nginx.conf` 对应容器内 `/etc/nginx/nginx.conf`
* `ENTRYPOINT`：必须指定 `daemon off;`，让 Nginx 以前台运行，保证容器持续存活
### 4.2 编写 docker-compose.yml（核心编排配置）
路径：`docker/docker-compose.yml`
作用：统一管理镜像构建、版本、端口、容器名、服务器推送等，**这是本次升级的核心**。
```yaml
# Compose 文件版本（3.8 兼容绝大多数 Docker 版本，稳定无坑）
version: '3.8'
# 定义服务（一个服务对应一个容器，这里只有 Nginx 前端服务）
services:
# 服务名：自定义，建议与项目名一致
mis-frontend:
# 构建配置：指定构建上下文和 Dockerfile 路径
build:
context: ../ # 构建上下文：回到项目根目录（保证 dist 能被访问）
dockerfile: docker/Dockerfile # Dockerfile 相对路径
# 镜像名称+版本：推送到开发服务器的核心标识
# 格式：服务器IP/项目名/镜像名:版本号，方便后续推送和版本管理
image: 服务器ip/mis-frontend:v1.0.0
# 固定容器名称：避免容器名自动生成（如 mis-frontend_1），方便运维管理
container_name: mis-frontend
# 端口映射：宿主机端口:容器端口
# 必须与 nginx.conf 中监听的端口一致（这里监听 8991 端口）
ports:
- "8991:8991"
# 重启策略：容器崩溃/服务器重启后自动重启，保证服务高可用
restart: always
# 环境变量：设置容器时区，避免日志时间与本地不一致
environment:
- TZ=Asia/Shanghai # 东八区时区
```
#### 关键避坑说明（重点！）
1. **不写 volumes 挂载** ：服务器上没有你本地 Windows 路径，挂载会导致 `invalid volume specification` 错误，我们已将代码打包进镜像，无需挂载
2. **不写 command 覆盖** ：Dockerfile 中已通过 `ENTRYPOINT` 指定启动命令，重复写会导致命令冲突
3. **端口必须一致** ：`ports` 中的宿主机端口和容器端口，必须与 `nginx.conf` 中 `listen` 的端口完全匹配
*** ** * ** ***
## 五、IDEA 一键部署（可视化操作，零命令行）
完成配置后，无需手动执行 `docker build/push` 命令，通过 IDEA 可视化界面一键完成全流程。
### 5.1 运行配置
1. 打开 `docker/docker-compose.yml` 文件
2. 点击文件左侧的 **绿色运行按钮 ▶️**（或右键文件 → 选择「Run 'docker-compose.yml'」）
3. IDEA 自动弹出运行配置框，无需额外修改，直接点击 **OK**
### 5.2 部署流程（IDEA 自动完成）
1. **构建镜像** ：根据 `build` 配置，读取 Dockerfile，在本地构建镜像，自动标记为 `ip/mis-frontend:v1.0.0`
2. **推送镜像**：将构建好的镜像推送到开发服务器的 Docker 仓库
3. **创建容器** ：在服务器上基于推送的镜像，创建名为 `mis-frontend` 的容器
4. **启动容器**：映射 8991 端口，设置自动重启，启动 Nginx 服务
5. **验证部署** ：部署完成后，IDEA 控制台显示「Started successfully」，表示部署成功
### 5.3 访问验证
在浏览器访问如果能看到前端项目页面，说明部署成功！
*** ** * ** ***
## 六、进阶操作（日常部署必备）
### 6.1 切换分支部署（核心优势）
当你切换项目分支（如 dev、test、feature）时，**无需修改任何配置**，直接：
1. 切换本地代码分支
2. 重新运行 `docker-compose.yml`
3. IDEA 自动：重新构建镜像（基于新分支代码）→ 推送 → 重启容器
真正实现"分支切换，一键部署"，彻底告别反复改配置的烦恼！
### 6.2 查看容器日志
1. IDEA 底部打开 **Services** 面板
2. 展开 Docker → Docker-compose: docker → mis → 找到 `mis-frontend`
3. 右键 → 选择 **View Logs**，实时查看 Nginx 运行日志，快速排查问题
### 6.3 停止/重启容器
1. 停止：Services 面板中找到容器 → 右键 → **Stop**
2. 重启：Services 面板中找到容器 → 右键 → **Restart**
3. 一键清理：在 `docker` 目录执行 `docker-compose down`（IDEA 终端中），停止并删除容器
### 6.4 版本升级（规范管理）
当项目迭代更新时，只需修改 `docker-compose.yml` 中的镜像版本：
```yaml
# 从 v1.0.0 升级到 v1.1.0
image: 服务器ip/mis-frontend:v1.1.0
```
重新运行即可，版本可追溯、可回滚，部署更安全。
*** ** * ** ***
## 七、常见问题及解决方案（避坑指南）
### 7.1 报错：invalid volume specification
**原因** ：配置中包含 `volumes` 挂载本地 Windows 路径，服务器上不存在该路径。
**解决** ：**完全删除 volumes 配置**，我们的代码已打包进镜像，无需本地挂载。
### 7.2 容器启动后立即退出
**原因** ：Nginx 未以前台运行，容器检测到进程退出后自动关闭。
**解决**：Dockerfile 中必须添加：
```dockerfile
ENTRYPOINT ["nginx", "-g", "daemon off;"]
```
### 7.3 报错：client version 1.52 is too new. Maximum supported API version is 1.40
**原因** ：本地 Docker 客户端版本高于服务器支持的 API 版本。
**解决**：IDEA Docker 配置添加环境变量：（我是修改的windows环境变量）
1. 打开 IDEA → File → Settings → Build, Execution, Deployment → Docker
2. 选中远程连接 → 点击「Advanced」→ 「Environment variables」→ 「+」
3. 添加：Name=`DOCKER_API_VERSION`，Value=`1.40`
4. 重启 IDEA 生效。
### 7.4 推送镜像失败：权限不足/连接超时
**原因** ：服务器 2375 端口未开放、防火墙拦截、Docker 未重启。
**解决**：
1. 检查服务器防火墙：`sudo firewall-cmd --add-port=2375/tcp --permanent && sudo firewall-cmd --reload`
2. 确认 Docker 已重启：`sudo systemctl restart docker`
3. 本地 ping 服务器 IP：`ping ip`，确保网络连通。
*** ** * ** ***
## 八、总结
本次升级的 **IDEA + docker-compose.yml 前端部署方案**，核心优势总结如下：
1. **配置即代码**：所有部署参数写在 yml 文件，提交 Git，全员共享，分支切换无需改配置
2. **一键全流程**：构建、推送、启动、停止全可视化，无需命令行操作，新手也能快速上手
3. **版本可控**：镜像带版本号，可追溯、可回滚，避免版本混乱
4. **稳定高可用**：固定容器名、端口，配置自动重启，保证服务持续可用
5. **适配多场景**：支持单服务部署，后续可轻松扩展 Java 服务、数据库等多服务协同
对于前端团队而言，这套方案**彻底解决了多分支部署的痛点**，让部署流程标准化、自动化，大幅提升开发效率。
后续新项目、新分支，只需复制这套 `docker` 目录，修改端口、镜像名和版本号，即可一键部署，真正实现"一次配置，到处运行"！
*** ** * ** ***
## 附：完整配置文件汇总
### 1. docker/Dockerfile
```dockerfile
FROM nginx:alpine
MAINTAINER huaiyu.zhang
ADD docker/nginx.conf /etc/nginx/
COPY dist/ /usr/share/nginx/html/
ENTRYPOINT ["nginx", "-g", "daemon off;"]
```
### 2. docker/docker-compose.yml
```yaml
version: '3.8'
services:
mis-frontend:
build:
context: ../
dockerfile: docker/Dockerfile
image: 服务器ip/mis-frontend:v1.0.0
container_name: mis-frontend
ports:
- "8991:8991"
restart: always
environment:
- TZ=Asia/Shanghai
```