Vue 3 + Vite项目Docker容器化与GitHub Actions自动化部署实战

1. 项目概述前端DevOps的核心价值2018年我第一次尝试将Docker用于前端项目部署时node_modules的版本冲突让整个团队浪费了三天时间。如今前端DevOps已经成为工程化标配这套基于Vue 3 Vite的技术栈配合GitHub Actions的自动化方案能让你在30分钟内完成从代码提交到生产环境部署的全流程。现代前端开发早已不是简单的HTML/CSS/JS组合当项目规模达到一定程度后你会发现测试环境的node版本与生产环境不一致导致API调用失败本地运行正常的代码在服务器上报错手动部署过程繁琐且容易遗漏步骤多环境配置管理混乱这正是我们需要前端DevOps的原因。通过Docker容器化保证环境一致性利用GitHub Actions实现自动化部署最终达到一次构建处处运行的理想状态。下面以Vue 3 Vite项目为例完整演示这套方案的实现过程。2. 环境准备与工具链配置2.1 基础环境搭建在开始前需要确保本地已安装Node.js 16推荐使用nvm管理多版本Docker DesktopMac/Windows或Docker EngineLinuxGit 2.30Vue CLI或直接使用Vite重要提示Windows用户需在BIOS中开启虚拟化支持VT-x/AMD-V否则Docker无法正常运行。可通过任务管理器→性能选项卡查看虚拟化是否已启用。# 验证环境是否就绪 node -v docker --version git --version2.2 创建Vue 3项目使用Vite初始化项目比传统Vue CLI更快且默认支持Vue 3npm create vitelatest my-vue-app --template vue cd my-vue-app npm install项目结构关键点vite.config.js- 构建配置文件public/- 静态资源目录src/- 源代码目录package.json- 已包含Vue 3和Vite依赖3. Docker容器化实战3.1 编写Dockerfile在项目根目录创建Dockerfile无扩展名# 使用官方Node镜像作为构建环境 FROM node:16-alpine as builder WORKDIR /app COPY package*.json ./ RUN npm install COPY . . RUN npm run build # 使用Nginx作为生产环境服务器 FROM nginx:alpine COPY --frombuilder /app/dist /usr/share/nginx/html COPY nginx.conf /etc/nginx/conf.d/default.conf EXPOSE 80 CMD [nginx, -g, daemon off;]这个多阶段构建方案使用Node镜像安装依赖并构建项目将生成的dist目录复制到Nginx镜像使用轻量级的Nginx Alpine镜像运行应用3.2 配置Nginx创建nginx.conf文件处理Vue路由的history模式server { listen 80; server_name localhost; location / { root /usr/share/nginx/html; index index.html; try_files $uri $uri/ /index.html; } # 处理API代理根据实际需求配置 # location /api { # proxy_pass http://backend:3000; # } }3.3 构建并运行容器# 构建Docker镜像注意最后的点 docker build -t vue-app . # 运行容器 docker run -d -p 8080:80 --name vue-container vue-app访问http://localhost:8080即可看到运行中的应用。通过以下命令管理容器# 查看运行中的容器 docker ps # 停止容器 docker stop vue-container # 删除容器 docker rm vue-container # 删除镜像 docker rmi vue-app4. GitHub Actions自动化部署4.1 配置仓库密钥在GitHub仓库的Settings → Secrets → Actions中添加DOCKERHUB_USERNAME- Docker Hub用户名DOCKERHUB_TOKEN- Docker Hub访问令牌4.2 编写CI/CD工作流创建.github/workflows/deploy.ymlname: Docker Build and Push on: push: branches: [ main ] pull_request: branches: [ main ] jobs: build: runs-on: ubuntu-latest steps: - uses: actions/checkoutv3 - name: Login to Docker Hub uses: docker/login-actionv2 with: username: ${{ secrets.DOCKERHUB_USERNAME }} password: ${{ secrets.DOCKERHUB_TOKEN }} - name: Build and push uses: docker/build-push-actionv4 with: push: ${{ github.ref refs/heads/main }} tags: ${{ secrets.DOCKERHUB_USERNAME }}/vue-app:latest4.3 高级部署策略对于生产环境推荐使用更完善的工作流name: Production Deployment on: push: tags: - v*.*.* jobs: deploy: runs-on: ubuntu-latest environment: production steps: - uses: actions/checkoutv3 - name: Extract version id: version run: echo VERSION${GITHUB_REF#refs/tags/} $GITHUB_ENV - name: Docker Build run: docker build -t ${{ secrets.DOCKERHUB_USERNAME }}/vue-app:${{ env.VERSION }} . - name: Docker Push run: | echo ${{ secrets.DOCKERHUB_TOKEN }} | docker login -u ${{ secrets.DOCKERHUB_USERNAME }} --password-stdin docker push ${{ secrets.DOCKERHUB_USERNAME }}/vue-app:${{ env.VERSION }} docker push ${{ secrets.DOCKERHUB_USERNAME }}/vue-app:latest - name: Deploy to Server uses: appleboy/ssh-actionmaster with: host: ${{ secrets.PRODUCTION_HOST }} username: ${{ secrets.SSH_USERNAME }} key: ${{ secrets.SSH_PRIVATE_KEY }} script: | docker pull ${{ secrets.DOCKERHUB_USERNAME }}/vue-app:${{ env.VERSION }} docker stop vue-app || true docker rm vue-app || true docker run -d -p 80:80 --name vue-app ${{ secrets.DOCKERHUB_USERNAME }}/vue-app:${{ env.VERSION }}5. 进阶优化与最佳实践5.1 多环境配置管理使用Vite的环境变量# .env.development VITE_API_BASEhttp://localhost:3000 # .env.production VITE_API_BASEhttps://api.example.com在代码中通过import.meta.env.VITE_API_BASE访问。Docker构建时通过--build-arg传递环境ARG ENVproduction ENV VITE_ENV${ENV} COPY .env.${VITE_ENV} .env5.2 镜像优化技巧使用.dockerignore排除不需要的文件node_modules .git .DS_Store *.md多阶段构建减少镜像体积前文Dockerfile已实现使用Alpine基础镜像合并RUN命令减少镜像层数5.3 安全加固措施使用非root用户运行容器FROM nginx:alpine RUN chown -R nginx:nginx /usr/share/nginx/html USER nginx定期更新基础镜像版本扫描镜像漏洞docker scan vue-app6. 常见问题排查6.1 Docker构建失败问题1npm install阶段报错解决方案检查node版本是否匹配清理缓存后重试docker builder prune npm cache clean --force问题2磁盘空间不足解决方案清理无用镜像docker system prune -a6.2 GitHub Actions执行失败问题1Docker Hub认证失败检查secrets是否正确设置确保令牌具有写入权限问题2SSH部署超时检查服务器安全组规则验证SSH密钥是否正确6.3 生产环境问题问题1白屏或404错误检查Nginx配置是否正确处理history路由验证静态资源路径问题2API请求跨域配置Nginx反向代理或设置正确的CORS头这套方案在我负责的多个中大型前端项目中稳定运行超过两年最大的收益是彻底解决了在我机器上能跑的问题。最近一次统计显示部署时间从原来的人工30分钟缩短到现在的全自动8分钟且部署成功率从85%提升到99.6%。