文章目录一、前言二、为什么使用 Docker 部署前端项目三、准备工作3.1 安装 Docker Desktop3.2 配置 Docker 镜像加速器可选但推荐四、项目结构和配置文件详解4.1 Dockerfile4.2 nginx.conf4.3 docker-compose.yml4.4 .dockerignore五、部署步骤方法一使用 Docker Compose推荐1. 进入项目目录2. 构建并启动容器3. 验证部署4. 访问应用5. 停止容器方法二使用 Docker 命令1. 构建镜像2. 运行容器3. 管理容器六、常见问题与解决方案问题 1无法连接到 Docker Hub问题 2ESLint 配置文件找不到问题 3端口被占用问题 4容器启动后无法访问问题 5修改代码后不生效七、容器管理最佳实践日常开发流程容器生命周期管理资源清理生产环境优化八、监控和日志本文将详细介绍如何使用 Docker 在本地部署一个基于 Vue3 Vite 的客户端渲染CSR前端项目包括完整的配置文件、部署流程和常见问题解决方案。一、前言在现代前端开发中Docker已经成为项目部署的标准工具之一。通过Docker我们可以将前端应用及其运行环境打包成一个独立的容器实现一次构建到处运行的目标。本文将以一个 Vue3 项目为例详细介绍如何使用Docker进行本地部署。本项目使用的技术栈前端框架Vue 3.4.21构建工具Vite 5.2.0UI 框架Element Plus 2.5.3包管理器pnpm 10.7.0容器化Docker Docker ComposeWeb 服务器Nginx (Alpine)二、为什么使用 Docker 部署前端项目优势环境一致性开发、测试、生产环境完全一致避免在我机器上能跑的问题快速部署一条命令即可完成部署无需手动配置 Nginx易于维护配置文件化版本可控资源隔离容器之间相互独立互不影响易于扩展可以轻松实现负载均衡和水平扩展适用场景本地开发环境搭建团队协作开发CI/CD 流程生产环境部署微服务架构三、准备工作3.1 安装 Docker DesktopWindows 用户访问 Docker Desktop 官网下载并安装 Docker Desktop for Windows启动 Docker Desktop验证安装docker--version docker-compose--version3.2 配置 Docker 镜像加速器可选但推荐在中国大陆访问Docker Hub可能较慢建议配置国内镜像源。打开Docker Desktop → Settings → Docker Engine添加以下配置{builder:{gc:{defaultKeepStorage:20GB,enabled:true}},experimental:false,registry-mirrors:[https://docker.m.daocloud.io,https://docker.1panel.live,https://hub.rat.dev]}如图所示点击Apply Restart重启 Docker。四、项目结构和配置文件详解前端项目结构主要添加Dockerfile、docker-compose.yml、nginx.conf、.dockerignore文件vue3/ ├── src/ # 源代码目录 ├── public/ # 静态资源 ├── dist/ # 构建输出目录自动生成 ├── node_modules/ # 依赖包 ├── package.json # 项目配置 ├── vite.config.ts # Vite 配置 ├── Dockerfile # Docker 镜像构建文件 ├── docker-compose.yml # Docker Compose 配置 ├── nginx.conf # Nginx 服务器配置 └── .dockerignore # Docker 忽略文件配置文件详解4.1 DockerfileDockerfile 采用多阶段构建策略分为构建阶段和运行阶段可以显著减小最终镜像体积。# 多阶段构建 # 第一阶段构建应用 FROM node:18-alpine AS builder # 设置工作目录 WORKDIR /app # 复制 package.json 和 lock 文件 COPY package*.json pnpm-lock.yaml ./ # 安装 pnpm RUN npm install -g pnpm10.7.0 # 安装依赖 RUN pnpm install --frozen-lockfile # 复制项目文件 COPY . . # 构建项目 RUN pnpm run build # 第二阶段运行应用 FROM nginx:alpine # 复制自定义 nginx 配置 COPY nginx.conf /etc/nginx/conf.d/default.conf # 从构建阶段复制构建产物到 nginx 目录 COPY --frombuilder /app/dist /usr/share/nginx/html/vue3 # 暴露端口 EXPOSE 80 # 启动 nginx CMD [nginx, -g, daemon off;]关键点解析多阶段构建第一阶段使用node:18-alpine构建应用第二阶段使用nginx:alpine运行应用最终镜像只包含 Nginx 和静态文件体积约 50-100MB依赖安装优化先复制package.json利用 Docker 缓存机制使用--frozen-lockfile确保依赖版本一致轻量级基础镜像使用 Alpine Linux镜像体积更小4.2 nginx.confNginx 配置文件负责处理 HTTP 请求和静态文件服务。server { listen 80; server_name localhost; # 设置根目录 root /usr/share/nginx/html; # 开启 gzip 压缩 gzip on; gzip_vary on; gzip_min_length 1024; gzip_types text/plain text/css text/xml text/javascript application/x-javascript application/xmlrss application/javascript application/json; # 处理 /vue3/ 路径 location /vue3/ { alias /usr/share/nginx/html/vue3/; try_files $uri $uri/ /vue3/index.html; # 设置缓存策略 location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff|woff2|ttf|eot)$ { expires 1y; add_header Cache-Control public, immutable; } } # 处理根路径重定向到 /vue3/ location / { return 301 /vue3/; } # 错误页面 error_page 404 /vue3/index.html; # 健康检查端点 location /health { access_log off; return 200 healthy\n; add_header Content-Type text/plain; } }配置亮点支持 Vue Router History 模式try_files $uri $uri/ /vue3/index.html确保所有路由都指向 index.htmlGzip 压缩减少传输数据量提升加载速度静态资源缓存对 JS、CSS、图片等资源设置 1 年缓存使用immutable标记浏览器永不重新验证健康检查端点/health端点用于监控服务状态4.3 docker-compose.ymlDocker Compose 简化了容器的管理和编排。version:3.8services:vue3-app:# 构建配置build:context:.dockerfile:Dockerfile# 容器名称container_name:vue3-app# 端口映射 (主机端口:容器端口)ports:-8080:80# 重启策略restart:unless-stopped# 环境变量可选environment:-NODE_ENVproduction# 网络配置可选networks:-vue3-network# 网络配置可选networks:vue3-network:driver:bridge配置说明build: 指定 Dockerfile 位置container_name: 自定义容器名称ports: 将容器的 80 端口映射到主机的 8080 端口restart: 容器退出时自动重启除非手动停止networks: 创建独立网络便于容器间通信4.4 .dockerignore排除不需要复制到镜像中的文件减小镜像体积。node_modules dist .git .gitignore .vscode *.md *.log .DS_Store Thumbs.db注意不要排除.eslintrc.cjs和.eslintignore因为构建过程可能需要这些文件。五、部署步骤方法一使用 Docker Compose推荐这是最简单的方式适合大多数场景。1. 进入项目目录cd d:\MyProjects\vue32. 构建并启动容器docker-compose up-d--build参数说明up: 启动服务-d: 后台运行detached mode--build: 构建镜像如图所示外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传部署成功3. 验证部署# 查看容器状态dockerps# 查看容器日志docker-compose logs-f# 健康检查Invoke-WebRequest-Uri http://localhost:8080/health-UseBasicParsing如图所示4. 访问应用打开浏览器访问http://localhost:8080/vue3/如图所示5. 停止容器# 停止并删除容器docker-compose down# 只停止容器不删除docker-compose stop方法二使用 Docker 命令如果需要更细粒度的控制可以使用原生 Docker 命令。1. 构建镜像docker build-t vue3-app:latest.2. 运行容器docker run-d-p 8080:80--name vue3-app vue3-app:latest3. 管理容器# 查看日志docker logs-f vue3-app# 停止容器docker stop vue3-app# 启动已停止的容器dockerstartvue3-app# 重启容器docker restart vue3-app# 删除容器dockerrmvue3-app六、常见问题与解决方案问题 1无法连接到 Docker Hub错误信息failed to fetch oauth token: Post https://auth.docker.io/token: dial tcp 108.160.172.1:443: connectex解决方案配置国内镜像加速器参见 #3.2 配置 Docker 镜像加速器。问题 2ESLint 配置文件找不到错误信息[vite-plugin-eslint] No ESLint configuration found in /app/src.解决方案从.dockerignore中移除.eslintrc.cjs和.eslintignorenode_modules dist .git .gitignore .vscode -.eslintignore -.eslintrc.cjs *.md *.log .DS_Store Thumbs.db问题 3端口被占用错误信息Bind for 0.0.0.0:8080 failed: port is already allocated解决方案修改docker-compose.yml中的端口映射ports:-8081:80# 改为其他端口问题 4容器启动后无法访问排查步骤检查容器是否正在运行dockerps查看容器日志docker logs vue3-app检查 Nginx 配置docker exec-it vue3-appcat/etc/nginx/conf.d/default.conf验证文件是否正确复制docker exec-it vue3-appls-la/usr/share/nginx/html/vue3/问题 5修改代码后不生效原因Docker 镜像是不可变的代码修改后需要重新构建。解决方案docker-compose down docker-compose up-d--build或使用一条命令docker-compose up-d--build--force-recreate七、容器管理最佳实践日常开发流程# 1. 启动容器docker-compose up-d# 2. 查看日志docker-compose logs-f# 3. 代码修改后重新部署docker-compose up-d--build# 4. 停止容器docker-compose down容器生命周期管理操作Docker ComposeDocker 命令启动docker-compose up -ddocker start vue3-app停止docker-compose stopdocker stop vue3-app重启docker-compose restartdocker restart vue3-app删除docker-compose downdocker rm vue3-app查看日志docker-compose logs -fdocker logs -f vue3-app资源清理# 删除停止的容器docker container prune# 删除未使用的镜像docker image prune# 清理所有未使用的资源docker system prune-a生产环境优化移除 sourcemap修改vite.config.tsbuild:{sourcemap:false,// 生产环境不生成 sourcemap}资源限制在docker-compose.yml中添加services:vue3-app:deploy:resources:limits:cpus:0.5memory:512M健康检查services:vue3-app:healthcheck:test:[CMD,wget,--quiet,--tries1,--spider,http://localhost/health]interval:30stimeout:10sretries:3日志管理services:vue3-app:logging:driver:json-fileoptions:max-size:10mmax-file:3八、监控和日志查看实时日志# Docker Composedocker-compose logs-f# Docker 命令docker logs-f vue3-app# 只查看最近 100 行docker logs--tail 100 vue3-app容器资源监控# 查看资源使用情况docker stats vue3-app# 查看容器详细信息docker inspect vue3-app 感谢阅读想了解更多 我的博客网站 | 记录思考分享干货 我的个人主页 | 关于我、开源项目