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 Desktop（Mac/Windows）或Docker Engine（Linux）
- Git 2.30+
- Vue CLI或直接使用Vite
重要提示：Windows用户需在BIOS中开启虚拟化支持（VT-x/AMD-V），否则Docker无法正常运行。可通过任务管理器→性能选项卡查看虚拟化是否已启用。
# 验证环境是否就绪 node -v docker --version git --version2.2 创建Vue 3项目
使用Vite初始化项目比传统Vue CLI更快，且默认支持Vue 3：
npm create vite@latest 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 --from=builder /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.yml：
name: Docker Build and Push on: push: branches: [ "main" ] pull_request: branches: [ "main" ] jobs: build: runs-on: ubuntu-latest steps: - uses: actions/checkout@v3 - name: Login to Docker Hub uses: docker/login-action@v2 with: username: ${{ secrets.DOCKERHUB_USERNAME }} password: ${{ secrets.DOCKERHUB_TOKEN }} - name: Build and push uses: docker/build-push-action@v4 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/checkout@v3 - 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-action@master 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_BASE=http://localhost:3000 # .env.production VITE_API_BASE=https://api.example.com在代码中通过import.meta.env.VITE_API_BASE访问。Docker构建时通过--build-arg传递环境：
ARG ENV=production 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-app
6. 常见问题排查
6.1 Docker构建失败
问题1：npm install阶段报错
- 解决方案：检查node版本是否匹配，清理缓存后重试
docker builder prune npm cache clean --force
问题2：磁盘空间不足
- 解决方案：清理无用镜像
docker system prune -a
6.2 GitHub Actions执行失败
问题1：Docker Hub认证失败
- 检查secrets是否正确设置
- 确保令牌具有写入权限
问题2：SSH部署超时
- 检查服务器安全组规则
- 验证SSH密钥是否正确
6.3 生产环境问题
问题1：白屏或404错误
- 检查Nginx配置是否正确处理history路由
- 验证静态资源路径
问题2：API请求跨域
- 配置Nginx反向代理
- 或设置正确的CORS头
这套方案在我负责的多个中大型前端项目中稳定运行超过两年，最大的收益是彻底解决了"在我机器上能跑"的问题。最近一次统计显示，部署时间从原来的人工30分钟缩短到现在的全自动8分钟，且部署成功率从85%提升到99.6%。