前端项目 Docker 化部署完整指南

qq_45535426

2082人浏览 · 2025-11-25 13:19:30

qq_45535426 · 2025-11-25 13:19:30 发布

今日新增技能！💪

本文档详细介绍前端项目（以 Vue 项目为例）从本地准备到服务器 Docker 部署的全流程，包含环境配置、打包、上传、容器化运行及后期维护等关键步骤，确保部署过程规范可复现。

一、本地项目准备阶段

在将项目部署到服务器前，需完成本地项目的搭建、联调、配置与打包，确保项目具备部署条件。

1. 项目初始化与本地验证

新建前端空项目（如 Vue、React 项目），执行本地运行命令（如npm run serve），在浏览器访问本地地址（通常为http://localhost:8080），确认项目运行正常、页面渲染符合预期。

2. 前后端联调（分离项目专属）

若为前后端分离架构，需先配置项目的网关 / 接口地址，确保本地项目能正常连接后端服务。

测试所有核心接口（如数据查询、提交、WebSocket 连接等），验证接口通断性与数据交互正确性，避免部署后因接口问题导致功能异常。

3. 配置 Docker 与 Nginx 文件

项目根目录需新增Dockerfile和nginx.conf两个核心配置文件，用于 Docker 镜像构建与 Nginx 服务配置。

（1）Dockerfile 配置

作用：基于 Nginx 基础镜像，将本地打包后的项目文件复制到镜像中，并替换默认 Nginx 配置。

\# 基于nginx:1.20稳定版镜像构建

FROM nginx:1.20

\# 将本地打包生成的dist文件夹，复制到镜像内的Nginx默认静态资源目录

COPY dist/ /usr/share/nginx/html/dist/

\# 用本地自定义的nginx.conf，替换镜像中默认的Nginx配置文件

COPY nginx.conf /etc/nginx/nginx.conf

（2）nginx.conf 配置

作用：配置 Nginx 端口、静态资源路径、接口代理、WebSocket 支持及 Gzip 压缩等，适配前端项目需求（如解决 Vue 路由刷新 404 问题）。

#user  nobody;
worker_processes  1;

#error_log  logs/error.log;
#error_log  logs/error.log  notice;
#error_log  logs/error.log  info;

#pid        logs/nginx.pid;

events {
    worker_connections  1024;
}

http {
    include       mime.types;
    default_type  application/octet-stream;
    sendfile        on;
    keepalive_timeout  65;

    # 上传最大大小
    client_max_body_size 100M;
    # 开启gzip打包
    gzip on;
    gzip_vary on;
    gzip_proxied any;
    gzip_comp_level 6;
    gzip_buffers 16 8k;
    gzip_http_version 1.1;
    gzip_types text/plain text/css application/json application/javascript text/xml application/xml application/xml+rss text/javascript;

    # 自定义变量 $connection_upgrade
    map $http_upgrade $connection_upgrade {
        default          keep-alive;  # 默认为 keep-alive，可以支持一般 http 请求
        'websocket'      upgrade;     # 如果为 websocket，则为 upgrade 可升级的。
    }

    server {
        listen 80; # 默认端口是 80，如果端口没被占用可以不用修改
        server_name  localhost;
        #charset koi8-r;
        #access_log logs/host.access.log main;

        location / {
            root /usr/share/nginx/html/dist/; # vue 项目的打包后的 dist
            try_files $uri $uri/ @router; # 指向下面的 @router，避免 vue 路由刷新时出现 404
            index index.html index.htm;
        }

        # 对应上面的 @router，用于处理 vue 的路由路径资源
        location @router {
            rewrite ^.*$ /index.html last;
        }

        location /stage-api/ {
            proxy_pass  http://服务器ip:后端访问端口; # 后台接口地址
            proxy_http_version 1.1;
            proxy_set_header Upgrade $http_upgrade; # 使用上面定义的变量
            proxy_set_header Connection $connection_upgrade;
            proxy_set_header Host $host;
            proxy_set_header X-Real-IP $remote_addr;
            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        }
        location ^~/ws1 {
            rewrite ^/ws1/(.*)$ /$1 break;
            proxy_pass http://服务器ip:后端访问端口;
            proxy_http_version 1.1;
            proxy_set_header Upgrade $http_upgrade;
            proxy_set_header Connection "upgrade";
            proxy_set_header X-real-ip $remote_addr;
            proxy_set_header X-Forwarded-For $remote_addr;
            proxy_set_header Host $host;
            }

    }
}

4. 项目打包

执行打包命令：根据项目package.json中scripts配置的打包命令执行（默认通常为npm run build，若自定义需替换为实际命令，如yarn build）。

验证打包结果：打包成功后，会在项目根目录生成dist文件夹（与src同级），该文件夹包含项目所有静态资源，是部署的核心文件。

二、服务器部署阶段

完成本地准备后，需通过工具连接服务器，上传文件并构建 Docker 镜像，最终启动容器运行项目。

1. 部署前准备

服务器信息：确认需部署的服务器IP地址、登录用户名（如 root、admin）及登录密码（需确保账号具备服务器操作权限）。

工具安装：下载并安装Xshell（用于连接服务器执行命令）和Xftp（用于上传本地文件到服务器），安装过程按默认步骤执行，注意选择自定义安装目录（避免 C 盘空间不足）。

2. Xshell 连接服务器

通过 Xshell 建立与服务器的 SSH 连接，步骤如下：

打开 Xshell，点击「新建」按钮创建连接；
在「连接」选项卡中配置：

名称：自定义（建议填写服务器 IP，方便后续识别）；
协议：选择SSH（默认）；
主机：输入服务器 IP 地址（必填，不可错误）；
端口号：默认22（若服务器修改过 SSH 端口，需填写实际端口）；

点击「确定」保存配置，双击左侧列表中的连接名称，按提示输入用户名和密码，完成连接（首次连接会提示 “接受主机密钥”，点击「接受」即可）。

3. Xftp 上传文件

通过 Xftp 将本地的dist文件夹、Dockerfile、nginx.conf上传到服务器，步骤如下：

在已连接的 Xshell 界面中，点击工具栏的「Xftp」图标（绿色图标），启动 Xftp（首次使用需完成账号注册，按提示操作即可）；
Xftp 启动后，自动同步 Xshell 的服务器连接，界面分为左右两部分：

左侧：本地文件目录，找到本地项目根目录（包含dist、Dockerfile、nginx.conf的目录）；
右侧：服务器文件目录，在服务器主目录（如/home/admin/）下新建文件夹，名称建议与项目名一致（如vue2-project-demo，方便后期维护）；

选中左侧的dist文件夹、Dockerfile、nginx.conf三个文件 / 文件夹，拖拽到右侧新建的项目目录中，等待上传完成（上传进度可在底部查看，确保无失败文件）。

4. 执行 Docker 命令部署项目

回到 Xshell 界面，在服务器终端执行以下命令，完成镜像构建与容器启动（所有命令需按顺序执行）：

（1）切换到 root 用户

sudo -i  # 执行该命令后，输入服务器登录密码（密码输入时不显示，输入完成按回车即可）

说明：切换 root 用户可避免后续命令因权限不足失败，若本身已为 root 用户，可跳过此步骤。

（2）进入项目目录

cd /home/admin/vue2-project-demo  # 路径需替换为服务器上项目文件夹的实际路径（即Xftp中新建的目录）

（3）构建 Docker 镜像

docker build -t vue2-project-demo .  # 命令说明：

\# -t：指定镜像名称（此处为vue2-project-demo，可自定义，建议与项目名一致）；

\# .：表示当前目录（需确保当前目录包含Dockerfile和nginx.conf，否则构建失败）

构建成功后，执行docker images命令，可在列表中看到名为vue2-project-demo的镜像（确认镜像存在，说明构建成功）。

（4）启动 Docker 容器

docker run -d -p 8080:80 --name vue2-app vue2-project-demo  # 命令说明：

\# -d：后台运行容器（守护进程模式）；

\# -p 8080:80：端口映射，将服务器的8080端口映射到容器的80端口（左侧为服务器端口，右侧为容器内Nginx监听端口）；

\# --name vue2-app：指定容器名称（此处为vue2-app，可自定义）；

\# vue2-project-demo：指定使用的镜像名称（需与步骤3中构建的镜像名称一致）

（5）验证容器运行状态

查看正在运行的容器：执行docker ps，若列表中存在vue2-app（容器名称），说明容器启动成功；

查看所有容器（含已停止）：执行docker ps -a（注意：原文档中docker ps a为语法错误，正确命令为docker ps -a），可查看容器的历史运行状态。

（6）访问项目

在本地浏览器中输入http://服务器IP:服务器端口（如http://192.168.1.100:8080），若能正常显示项目页面，且接口请求正常，说明部署成功。

三、常见问题与维护阶段

部署后若出现问题，可使用以下命令进行容器管理；若需更新项目代码，需按流程重新构建镜像。

1. 容器管理常用命令

操作需求	命令	说明
启动已停止容器	`docker start vue2-app`	需替换为实际容器名称
停止运行中容器	`docker stop vue2-app`	停止容器但不删除，可后续启动
删除已停止容器	`docker rm vue2-app`	容器删除后需重新启动镜像生成新容器
重启容器	`docker restart vue2-app`	建议优先使用`stop`再`start`，避免异常
查看容器日志	`docker logs -f vue2-app`	实时查看容器运行日志，排查接口 / 服务问题

2. 项目更新流程

当本地代码更新后，需重新部署以同步线上环境，步骤如下：

本地重新打包：执行npm run build，生成新的dist文件夹；
上传新文件：通过 Xftp 删除服务器项目目录中的旧dist文件夹，上传新的dist文件夹（或直接覆盖）；
删除旧容器与镜像：

停止旧容器：docker stop vue2-app；
删除旧容器：docker rm vue2-app；
删除旧镜像：docker rmi vue2-project-demo（需确保镜像无其他容器使用）；

重新构建镜像与启动容器：重复「二、4」中的步骤 3（构建镜像）和步骤 4（启动容器），完成更新。

注意事项

端口冲突：若服务器 8080 端口已被占用，需修改docker run命令中的服务器端口（如-p 8081:80，确保端口未被其他服务使用）；
接口地址：nginx.conf中的proxy_pass需替换为实际后端接口地址，避免因地址错误导致接口不通；
权限问题：若执行docker命令时提示 “权限不足”，需确认当前用户为 root，或通过sudo前缀执行命令（如sudo docker build ...）；
镜像清理：服务器长期部署后，会积累大量无用镜像，可通过docker system prune -a清理未使用的镜像与容器（执行前需确认无重要数据）。