Vue 项目部署指南

大白话解释： 部署就是"把你的代码放到服务器上，让用户能访问"。有几种方式：

• Docker：打包成"集装箱"，放到任何服务器上都能跑
• GitHub Pages：免费，适合个人项目和文档站
• Vercel/Netlify：自动部署，不用管服务器

为什么要了解不同部署方式？

• Docker：适合有自己服务器的团队，环境一致，易于扩展
• GitHub Pages：免费、简单，但只支持静态站点
• Vercel/Netlify：零配置，自动 CI/CD，适合中小型项目

部署的基本流程：

1. 构建项目（yarn build）
2. 把构建产物（dist/ 目录）放到服务器
3. 配置 Web 服务器（Nginx）指向构建产物
4. 配置 HTTPS（可选但推荐）

Vue 3 + Vite 项目的常见部署方式，包括 Docker、GitHub Pages、Vercel / Netlify。

---

构建产物

# 构建生产版本
yarn build

# 预览构建产物
yarn preview

构建产物默认输出到 dist/ 目录，是纯静态文件，可部署到任意静态服务器。

---

Docker 部署

Dockerfile

# 第一阶段：构建阶段（builder）
FROM node:20-alpine AS builder                   # 使用 Node.js 20 的 Alpine 镜像（体积小）
WORKDIR /app                                      # 设置工作目录为 /app
COPY package.json yarn.lock ./                    # 复制依赖文件（利用 Docker 缓存层）
RUN yarn install --frozen-lockfile                # 安装依赖（--frozen-lockfile 确保版本一致）
COPY . .                                          # 复制项目文件（依赖层已缓存，只复制变化的代码）
RUN yarn build                                    # 构建生产版本（输出到 dist/ 目录）

# 第二阶段：运行阶段
FROM nginx:alpine                                 # 使用 Nginx 的 Alpine 镜像
COPY --from=builder /app/dist /usr/share/nginx/html  # 从构建阶段复制 dist 目录到 Nginx 默认目录
COPY nginx.conf /etc/nginx/conf.d/default.conf    # 复制自定义 Nginx 配置
EXPOSE 80                                         # 声明容器监听 80 端口
CMD ["nginx", "-g", "daemon off;"]                # 启动 Nginx（前台运行，Docker 要求）

验证 Docker 构建是否成功：

# 1. 构建镜像
docker build -t my-vue-app .

# 2. 查看镜像
docker images | grep my-vue-app

# 3. 运行容器
docker run -d -p 80:80 my-vue-app

# 4. 访问 http://localhost 验证
curl http://localhost

# 5. 查看容器日志
docker logs <container_id>

nginx.conf

server {
  listen 80;                                        # 监听 80 端口（HTTP）
  server_name example.com;                          # 服务器域名（替换为实际域名）
  root /usr/share/nginx/html;                       # 静态文件根目录
  index index.html;                                 # 默认首页文件

  # Gzip 压缩（减少传输体积，提高加载速度）
  gzip on;                                          # 启用 Gzip 压缩
  gzip_types text/plain text/css application/json application/javascript text/xml;  # 压缩的文件类型
  gzip_min_length 1024;                             # 小于 1KB 的文件不压缩（压缩效果不明显）

  # 静态资源缓存（文件名带 hash，可长期缓存）
  location /assets/ {
    expires 1y;                                     # 缓存 1 年
    add_header Cache-Control "public, immutable";   # 公共缓存，不可变
  }

  # SPA 路由（Vue Router history 模式必须配置）
  location / {
    try_files $uri $uri/ /index.html;              # 所有路径都回退到 index.html
  }

  # API 代理（将 /api 请求代理到后端服务）
  location /api {
    proxy_pass http://backend:8080;                 # 后端服务地址（容器名:端口）
    proxy_set_header Host $host;                    # 传递原始 Host 头
    proxy_set_header X-Real-IP $remote_addr;        # 传递客户端真实 IP
  }
}

验证 Nginx 配置是否生效：

# 1. 测试配置文件语法
docker exec <container_id> nginx -t

# 2. 重新加载配置（不重启容器）
docker exec <container_id> nginx -s reload

# 3. 测试 SPA 路由
curl http://localhost/about    # 应该返回 index.html

# 4. 测试 API 代理
curl http://localhost/api/user # 应该代理到后端服务

# 5. 测试静态资源缓存
curl -I http://localhost/assets/index.js  # 查看 Cache-Control 头

构建 & 运行

# 构建镜像
docker build -t my-vue-app .

# 运行容器
docker run -d -p 80:80 my-vue-app

---

GitHub Pages

使用 GitHub Actions 自动部署。

# .github/workflows/deploy.yml
name: Deploy                                        # 工作流名称
on:
  push:
    branches: [main]                                # 触发条件：push 到 main 分支
jobs:
  build-and-deploy:                                 # 作业名称
    runs-on: ubuntu-latest                          # 运行环境：最新 Ubuntu
    steps:
      - uses: actions/checkout@v4                   # 检出代码
      - uses: actions/setup-node@v4                 # 安装 Node.js
        with:
          node-version: 20                          # Node.js 版本
          cache: yarn                               # 启用 yarn 缓存（加速安装）
      - run: yarn install --frozen-lockfile         # 安装依赖（--frozen-lockfile 确保版本一致）
      - run: yarn build                             # 构建项目
      - uses: peaceiris/actions-gh-pages@v4         # 部署到 GitHub Pages
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }} # 使用 GitHub 自动生成的 Token
          publish_dir: ./dist                       # 部署 dist 目录

验证 GitHub Actions 是否成功：

# 1. 推送代码到 main 分支
git push origin main

# 2. 在 GitHub 仓库页面 → Actions 标签页查看工作流状态

# 3. 绿色勾表示成功，红色叉表示失败

# 4. 点击工作流查看详细日志

# 5. 部署成功后，访问 https://<username>.github.io/<repo>/ 验证

⚠️ 如果项目部署在子路径（如 https://user.github.io/repo/），需要在 vite.config.ts 中设置 base: '/repo/'。

---

Vercel / Netlify

Vercel

// vercel.json
{
  "buildCommand": "yarn build",
  "outputDirectory": "dist",
  "framework": "vite"
}

Netlify

# netlify.toml
[build]
  command = "yarn build"
  publish = "dist"

💡 Vercel 和 Netlify 会自动检测 Vite 项目，通常无需额外配置。

---

常见问题

刷新页面 404

SPA 路由需要服务器将所有路径回退到 index.html：

# nginx
location / {
  try_files $uri $uri/ /index.html;
}

静态资源路径错误

如果部署在子路径，设置 base：

// vite.config.ts
export default defineConfig({
  base: '/my-app/',  // 部署在 /my-app/ 子路径
})

环境变量

构建时的环境变量在 vite build 时注入，不是运行时：

# 构建时指定模式
vite build --mode production

---

验证部署成功

Docker 部署验证

# 1. 检查容器运行状态
docker ps | grep my-vue-app

# 2. 检查容器日志
docker logs <container_id>

# 3. 访问应用
curl http://localhost

# 4. 测试 SPA 路由
curl http://localhost/about

# 5. 测试 API 代理
curl http://localhost/api/user

GitHub Pages 部署验证

# 1. 检查 GitHub Actions 状态
# 在仓库 → Actions 标签页查看

# 2. 检查 gh-pages 分支
git fetch origin
git log origin/gh-pages --oneline -5

# 3. 访问 GitHub Pages URL
# https://<username>.github.io/<repo>/

# 4. 测试页面路由
# 点击不同链接，确保 SPA 路由正常工作

# 5. 检查静态资源
# 打开浏览器 DevTools → Network，查看资源加载状态

Vercel/Netlify 部署验证

# 1. 检查构建日志
# 在 Vercel/Netlify 控制台查看构建状态

# 2. 检查部署 URL
# Vercel: https://<project>.vercel.app
# Netlify: https://<project>.netlify.app

# 3. 测试自动部署
# 推送代码后，应该自动触发重新部署

# 4. 检查环境变量
# 确保环境变量在控制台中正确配置

---

参考

• Vite 部署指南
• GitHub Pages 文档
• Vercel 文档