Vue / 系统课时
多环境构建与部署
多环境构建与部署
多环境交付的关键不是复制几套配置,而是让同一份 Vue 代码按明确的 mode 生成可追溯产物,并让静态资源路径、Nginx 回退和发布脚本保持一致。本节完成一套可验证、可回滚的部署基线。
学习目标
- 用 Vite mode 管理测试、预发和生产环境的公开配置
- 让资源
base、Nginx 路由回退与部署目录保持一致 - 用版本化目录和原子软链接切换降低发布与回滚风险
把环境差异收敛到构建输入
Vite 会按 mode 读取环境文件。前端真正需要区分的通常是 API 地址、静态资源公共路径和版本号;浏览器可见变量使用 VITE_ 前缀。密钥、数据库口令和服务端令牌不能放进这些文件,因为构建后它们会进入客户端产物。
下面是两个环境文件的片段示例,实际项目应把域名替换成自己的环境地址:
# .env.staging
VITE_API_BASE=https://api-staging.example.com
VITE_PUBLIC_BASE=/
# .env.production
VITE_API_BASE=https://api.example.com
VITE_PUBLIC_BASE=/vite.config.ts 只读取允许暴露给前端的变量,并把公共路径绑定到当前 mode:
import { defineConfig, loadEnv } from 'vite'
export default defineConfig(({ mode }) => {
const env = loadEnv(mode, process.cwd(), 'VITE_')
return {
base: env.VITE_PUBLIC_BASE || '/',
build: {
outDir: 'dist',
sourcemap: false
}
}
})在现有 package.json 中加入构建脚本,下面是片段示例:
{
"scripts": {
"build:staging": "vite build --mode staging",
"build:production": "vite build --mode production"
}
}执行预发构建并检查入口文件:
npm run build:staging >/dev/null && test -f dist/index.html && echo "dist ready"预期输出
dist ready如果生产站点部署在 /console/ 等子路径,VITE_PUBLIC_BASE 必须改成同一前缀,并同步调整 Web 服务器映射;否则常见现象是首页能打开,但 JS、CSS 请求落到错误路径而返回 404。
配置 Nginx 的静态文件与路由回退
Vue Router 使用 history 模式时,浏览器直接访问 /orders/123 会先到 Nginx。服务器并不知道这是前端路由,因此找不到真实文件时必须回退到 index.html,再由 Vue Router 接管。
server {
listen 80 default_server;
server_name _;
root /srv/www/frontend/current;
index index.html;
location = /index.html {
add_header Cache-Control "no-cache";
}
location / {
try_files $uri $uri/ /index.html;
}
}验证 Nginx 配置语法:
nginx -t预期输出
nginx: configuration file <PATH> syntax is ok
nginx: configuration file <PATH> test is successful<PATH> 是机器上的实际 Nginx 配置路径。若深层路由刷新返回 404,先检查 try_files;若只有静态资源 404,则优先核对 Vite 的 base 与实际挂载路径是否一致。
用版本化目录完成原子发布
不要直接覆盖正在服务的目录。更稳妥的做法是把每次构建放入独立 release 目录,完整复制成功后再切换 current 软链接;回滚时只需把软链接重新指向上一个 release。
#!/usr/bin/env bash
set -euo pipefail
: "${ARTIFACT_DIR:=dist}"
: "${DEPLOY_ROOT:=/srv/www/frontend}"
RELEASE_ID="${RELEASE_ID:-$(date +%Y%m%d%H%M%S)}"
RELEASE_DIR="$DEPLOY_ROOT/releases/$RELEASE_ID"
CURRENT_LINK="$DEPLOY_ROOT/current"
NEXT_LINK="$DEPLOY_ROOT/.current-$RELEASE_ID"
test -f "$ARTIFACT_DIR/index.html"
mkdir -p "$RELEASE_DIR"
cp -a "$ARTIFACT_DIR/." "$RELEASE_DIR/"
rm -f "$NEXT_LINK"
ln -s "$RELEASE_DIR" "$NEXT_LINK"
mv -Tf "$NEXT_LINK" "$CURRENT_LINK"
printf 'released %s\n' "$RELEASE_ID"预期输出
released <ID><ID> 对应本次 release 标识,默认由当前时间生成。mv -T 适用于 Linux 部署机;软链接与 release 目录应位于同一文件系统,以保持切换行为简单可控。

发布后做最小验收
发布完成后至少验证首页、静态资源和 history 回退。下面的检查故意请求一个不存在的服务端文件路径;若 SPA 回退生效,Nginx 仍应返回前端入口的 200。
curl -o /dev/null -s -w '%{http_code}\n' http://127.0.0.1/non-existent-client-route预期输出
200还应确认页面实际调用的是目标环境 API,并记录本次 release 标识。若新版本异常,优先停止继续发布,再将 current 指回上一版 release;版本化目录使回滚不依赖重新构建,能显著缩短恢复路径。