构建部署与 history 回退

学习目标

构建之后的最后一步：把 dist/ 部署出去，并让「直接访问深链接」「刷新页面」都不 404。这一节掌握静态托管与 Nginx 两种部署方式、history 模式的服务端回退配置，以及部署前的验收清单。

问题场景

npm run build 生成了 dist/，传到静态服务器，首页能打开。用户分享 /courses/v01 链接给对方，对方打开是 404——因为服务器上没有 courses/v01 这个文件，SPA 的路由只存在于客户端。刷新当前页面同样 404。这是 history 模式部署最经典的坑。

核心解释

SPA 的 history 模式依赖「所有未匹配的路径都返回 index.html」，由前端路由接管。不同托管方式配置不同：

静态托管（Netlify / Vercel / Cloudflare Pages）：加一条回退规则。Netlify 用 _redirects 文件：

/*  /index.html  200

Vercel 用 vercel.json：

{
  "rewrites": [{ "source": "/(.*)", "destination": "/index.html" }]
}

Nginx（自建服务器最常见）：

server {
  listen 80;
  server_name example.com;
  root /var/www/my-vue-app/dist;
  index index.html;

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

  # 带哈希的静态资源可以长缓存
  location /assets/ {
    expires 1y;
    add_header Cache-Control "public, immutable";
  }
}

try_files $uri $uri/ /index.html 是关键：先找真实文件，找不到就回退到 index.html。/assets/ 下的文件名带内容哈希，可以放心长缓存；index.html 本身不要缓存（否则用户拿不到新版本），Nginx 默认不设 expires 即可。

API 代理：生产环境前端与后端不同域时，同样在 Nginx 配 location /api/ { proxy_pass http://127.0.0.1:8080; }，把跨域留在服务端解决。

部署验收清单：构建产物无报错 → 首页可访问 → 深链接直接打开不 404 → 刷新不 404 → 静态资源 200 且带缓存头 → 接口请求地址正确（不是 localhost）→ 控制台无报错。

示例拆解

一个从构建到上线的完整命令序列（自建服务器）：

# 本地构建
npm run build && ls dist        # index.html + assets/

# 上传（rsync 支持断点与增量）
rsync -avz --delete dist/ user@server:/var/www/my-vue-app/dist/

# 服务器（首次配置后只需 reload）
sudo nginx -t && sudo systemctl reload nginx

# 用 vite preview 模拟静态服务器（内置 SPA 回退）
npm run preview
# 访问 http://localhost:4173/courses/v01（不存在的路径）：应返回 index.html + 前端 404 页

注意 --delete 会删掉服务器上多余的文件——用之前确认目标目录只是产物目录，不要指到用户数据目录。vite preview 内置 history 回退，所以它验证不了 Nginx 配置；上线后必须用真实域名再测一次深链接。

动手任务

1. 构建项目并用 npm run preview 验证深链接与刷新。
2. 写一份 Nginx 配置（try_files + /assets/ 缓存头），用 nginx -t 校验语法（没有 Nginx 就用 Docker 起一个）。
3. 把部署验收清单变成脚本：curl -I 检查首页 200、深链接 200、静态资源带 cache-control。

常见错误

• 只部署 index.html 不部署 assets：页面白屏，控制台 404。整目录上传。
• Nginx 没配 try_files：深链接 404。这是 SPA 部署第一坑。
• 给 index.html 设了长缓存：用户永远拿不到新版本，改了代码像没生效。
• 生产包里的接口地址还是 localhost：环境变量没切或构建时用了开发模式。

检查与复盘

• 能写出 Nginx 的 SPA 回退与静态资源缓存配置
• 能说出「深链接 404」的根因与三种托管的修复方式
• 能按验收清单逐项验证一次真实部署

参考资料

• Vue 官方文档「生产部署」：部署选项与注意事项
• Vite 官方文档「构建」：preview 与产物结构
• Nginx 官方文档：try_files 指令