Vue / 系统课时
部署后台应用
部署后台应用
本课将已经验证过的 dist 目录部署到 Nginx:静态文件由服务器直接返回,前端路由刷新时回退到入口页,带哈希的资源使用长期缓存,/api/ 请求则转发给后端服务。
学习目标
- 将构建产物发布到稳定目录,并保留可重复执行的部署步骤。
- 正确配置单页应用回退、差异化缓存和接口反向代理。
- 通过配置检查、HTTP 状态码和响应头完成上线验收。
部署拓扑与请求路径
本例约定前端访问前缀为 /admin/,构建产物位于服务器的 /srv/www/admin/。Nginx 以 /srv/www 为站点根目录,因此浏览器请求 /admin/assets/app.<ID>.js 时,会读取 /srv/www/admin/assets/app.<ID>.js。
页面请求和接口请求必须走不同链路:/admin/ 及其静态资源由 Nginx 处理,找不到真实文件的前端路由回退到 /admin/index.html;/api/ 则代理到监听在 127.0.0.1:8080 的后端服务。

先在本地完成标准生产构建,再把 dist 内容同步到服务器目录。下面命令在目标服务器执行;--delete 会删除目标目录中源目录已不存在的文件,因此必须确认变量没有指向其他站点。
DEPLOY_ROOT=/srv/www/admin
sudo mkdir -p "$DEPLOY_ROOT"
sudo rsync -a --delete dist/ "$DEPLOY_ROOT"/
test -f "$DEPLOY_ROOT/index.html" && test -d "$DEPLOY_ROOT/assets" && echo "UPLOAD_OK"预期输出如下。
UPLOAD_OK生产发布更稳妥的做法是先同步到带版本号的目录,再切换符号链接;本课使用固定目录突出 Nginx 规则。无论采用哪种方式,都不要在服务器上直接修改打包后的 JavaScript,因为下一次发布会覆盖这些改动,也无法回溯源代码。
配置 Nginx
将以下配置保存为 /etc/nginx/conf.d/vue-admin.conf。示例监听 HTTP 80 端口,域名、证书和安全响应头应按实际环境补充。
server {
listen 80;
server_name admin.example.com;
root /srv/www;
index index.html;
location ^~ /admin/assets/ {
add_header Cache-Control "public, max-age=31536000, immutable" always;
try_files $uri =404;
}
location /admin/ {
add_header Cache-Control "no-cache" always;
try_files $uri $uri/ /admin/index.html;
}
location /api/ {
proxy_pass http://127.0.0.1:8080/;
proxy_http_version 1.1;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}
}try_files 先查找真实文件,只有页面路由不存在时才返回入口页,因此不会把缺失的 JavaScript 错误伪装成 HTML。资源文件名包含内容哈希,内容变化后 URL 也会变化,适合使用一年缓存和 immutable;入口页引用最新哈希文件,必须使用 no-cache 以便浏览器及时重新验证。
proxy_pass 末尾的 / 会把 /api/users 转发为后端的 /users。若后端路由本身包含 /api 前缀,应改成不带末尾斜杠的 proxy_pass http://127.0.0.1:8080;,否则会出现接口路径不匹配。
验证部署与定位故障
先检查配置语法并平滑重载,再验证首页、深层路由和静态资源缓存。命令会自动选择一个已构建的 JavaScript 文件;若项目没有 JavaScript 产物,应改为实际存在的资源扩展名。
ASSET_NAME=$(find /srv/www/admin/assets -maxdepth 1 -type f -name '*.js' -printf '%f\n' | head -n 1)
sudo nginx -t
sudo systemctl reload nginx
curl -sSI http://127.0.0.1/admin/ | sed -n '1p;/[Cc]ache-[Cc]ontrol/p'
curl -sSI http://127.0.0.1/admin/users/42 | sed -n '1p'
curl -sSI "http://127.0.0.1/admin/assets/$ASSET_NAME" | sed -n '1p;/[Cc]ache-[Cc]ontrol/p'预期结果的关键行如下。Nginx 版本不同可能让语法检查文本略有差异,但状态码与缓存策略应一致。
nginx: configuration file /etc/nginx/nginx.conf test is successful
HTTP/1.1 200 OK
Cache-Control: no-cache
HTTP/1.1 200 OK
HTTP/1.1 200 OK
Cache-Control: public, max-age=31536000, immutable接口代理需要在后端健康时单独验证。将 <PATH> 替换为项目真实存在且无需登录的健康检查路径。
curl -sS -o /dev/null -w '%{http_code}\n' http://127.0.0.1/api/<PATH>预期结果如下。
200刷新页面出现 404,优先检查 location /admin/ 的回退和 Vite 的 base 是否一致;脚本返回 text/html,通常表示静态文件缺失后错误地回退到了入口页;接口返回 502,则检查后端监听地址、进程状态和防火墙,而不是修改前端路由。