Vue项目部署到香港服务器后,如何配置Web入口并验证静态资源访问?
目标状态不是“首页能打开”,而是域名通过 HTTPS 进入正确的 Vue 发布目录,刷新前端路由仍能返回页面,JavaScript、CSS、字体和图片按正确路径与类型返回,缺失资源不会被误判为成功。Vue 项目部署到香港服务器后,通常由 Nginx 提供这些静态文件,不需要在生产环境长期运行开发服务器。
这次变更应只调整 Web 入口和静态资源发布,不同时改动 API、数据库或网络规则。主要风险是入口指向错误目录、构建路径与部署路径不一致,以及新旧页面引用的资源不匹配。作为变更负责人,应先保留原配置与上一版产物,再分别验证域名入口、前端路由和真实资源请求,不能仅凭一次首页访问判断上线完成。
围绕Vue项目的Web入口与静态资源部署,A5数据提供香港物理服务器租用,涵盖常规建站、Xeon Gold及AMD EPYC等产品系列。SSD或NVMe存储可承载前端构建产物、多个发布版本及站点日志,配合不同档位的处理器与内存,为Nginx站点和业务后台提供运行资源;香港产品中的CN2与国际带宽方案,则为面向不同访问地区的页面与静态资源分发提供网络基础。
一、现状核对:确认请求实际走到哪里
以下示例采用 Ubuntu 22.04/24.04、已安装的 Nginx 和 systemd,Vue 项目使用 Vite 构建,并部署在域名根路径。域名以 app.example.com 为例,目录统一为:
/srv/www/vue-app/
├── current -> releases/上一版本
└── releases/
├── 上一版本/
└── 本次版本/
current 是入口软链接,每个版本目录保存完整构建产物。若现有站点使用普通目录,应先独立完成版本目录整理,保持原站点可访问,再进行本次切换;不要直接用软链接覆盖正在使用的目录。
确认域名、端口与生效配置
变更前核对以下内容:
- 域名的 A 记录是否指向香港服务器公网 IPv4;若存在 AAAA 记录,IPv6 入口也必须可用。
- 域名前是否接入 CDN、负载均衡或其他入口服务;浏览器看到的结果是否可能来自缓存。
- 80、443 端口是否按计划开放,Nginx 是否正在监听。
- 目标域名由哪个
server块处理,是否存在重复的server_name。 - 当前证书是否覆盖该域名,证书文件与私钥路径是否正确。
可先执行只读检查:
sudo systemctl status nginx --no-pager
sudo nginx -t
sudo ss -lntp | grep -E ':(80|443)\b'
sudo nginx -T
readlink -f /srv/www/vue-app/current
nginx -T 输出可能包含内部地址或敏感配置,不应直接公开。若端口未监听,先查服务;若本机正常、外部连接超时,再检查云平台访问控制和主机防火墙。不要为验证站点而关闭整个防火墙,任何规则调整都应单独记录原规则、影响范围及恢复方法。
确认构建路径与路由模式
构建资源路径决定浏览器请求哪个 URL,Nginx 的 root 决定这个 URL 从哪里读取文件,两者必须对应。
本文按根路径部署,Vite 的 base 使用 /:
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
export default defineConfig({
plugins: [vue()],
base: '/'
})
如果实际部署在 /console/,就需要同时调整 Vite base、Vue Router 的基础路径和 Nginx 映射,不能只改其中一项。使用 Vue CLI 的项目应核对 publicPath,不要套用 Vite 配置项。
路由也要单独确认:history 模式需要服务端对页面路由回退到 index.html;hash 模式的片段不发送给服务器,通常不需要这类回退。无论哪种模式,真实静态资源都应正常返回,缺失文件都应返回 404。
二、变更准备:备份配置,保留完整发布包
本文约定 /etc/nginx/sites-available/vue-app.conf 是该域名已经启用的站点配置,current 已指向上一版发布目录。若现场路径不同,应先替换示例路径,不能另外新增一个同域名配置来“覆盖”旧入口。
先保存可恢复状态:
CHANGE_ID=$(date +%Y%m%d-%H%M%S)
BACKUP_DIR="/var/backups/vue-app/$CHANGE_ID"
sudo install -d -m 0700 "$BACKUP_DIR"
sudo cp -a /etc/nginx/sites-available/vue-app.conf "$BACKUP_DIR/"
readlink -f /srv/www/vue-app/current \
| sudo tee "$BACKUP_DIR/previous-release.txt" >/dev/null
sudo sh -c "nginx -T > '$BACKUP_DIR/nginx-before.txt' 2>&1"
配置备份应保存在受限目录中。上一版发布目录不得删除;如果原目录曾被原地修改,还应另做完整副本或归档,单独记录路径并不足以恢复内容。
构建应在受控构建机或 CI 中完成,使用项目约定的 Node.js 版本及包管理器。采用 npm 且有有效锁文件时,可执行:
npm ci
npm run build
test -f dist/index.html
find dist -maxdepth 2 -type f | head -n 20
只上传构建产物,不上传开发服务器、源代码仓库或含密钥的环境文件。构建期写入前端的变量会进入浏览器,不能把它们当作秘密保存位置。
还有一个容易遗漏的风险:保留旧版本目录,并不等于旧浏览器会话仍能访问旧资源。切换后,/assets/旧文件名.js 会从新目录查找。可选择版本化资源 URL,或将仍被引用的旧哈希资源保留到新发布包中;后一种方式仅适用于文件名随内容变化的资源,不能让同名旧文件覆盖新文件。无法保障兼容时,应明确维护窗口,而不是把切换描述为无感发布。
三、分步实施:先准备产物,再调整入口
1. 上传到独立版本目录
下面命令在服务器执行,/tmp/vue-dist/ 表示已上传并核验的本次产物:
RELEASE="/srv/www/vue-app/releases/$CHANGE_ID"
sudo install -d -m 0755 "$RELEASE"
sudo cp -a /tmp/vue-dist/. "$RELEASE/"
sudo test -f "$RELEASE/index.html"
不要在 current 指向的目录里覆盖文件,否则请求可能读到新 HTML 与旧资源的混合状态。
确认 Nginx worker 的运行用户,再验证其读取权限:
sudo nginx -T 2>&1 | grep -E '^user '
sudo -u www-data test -r "$RELEASE/index.html"
第二条仅适用于 worker 用户确实为 www-data 的环境。还应检查目录逐级遍历权限及实际 JS 文件的读取权限;不要用递归 777 解决权限问题,确需调整时只修改专用发布目录,并记录原权限以便恢复。
2. 修改目标站点配置
以下配置适用于“根路径静态站点、已有可用证书”的场景。证书路径是示例,必须替换为现场路径;尚未签发证书时,应先完成证书准备,不要关闭证书校验来通过验收。
修改的是已备份的站点文件,影响范围为该域名。其他站点和已有 API 转发配置应保持不变。
server {
listen 80;
server_name app.example.com;
return 301 https://app.example.com$request_uri;
}
server {
listen 443 ssl;
server_name app.example.com;
ssl_certificate /etc/letsencrypt/live/app.example.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/app.example.com/privkey.pem;
root /srv/www/vue-app/current;
index index.html;
include /etc/nginx/mime.types;
default_type application/octet-stream;
access_log /var/log/nginx/vue-app.access.log;
error_log /var/log/nginx/vue-app.error.log warn;
location = /index.html {
add_header Cache-Control "no-cache" always;
}
location ^~ /assets/ {
try_files $uri =404;
add_header Cache-Control "public, max-age=300";
}
location ~* \.(?:js|mjs|css|map|json|png|jpg|jpeg|gif|svg|webp|ico|woff|woff2|ttf|wasm)$ {
try_files $uri =404;
add_header Cache-Control "no-cache";
}
# 本例不提供同域 API,避免 API 请求落入页面回退。
location = /api {
return 404;
}
location ^~ /api/ {
return 404;
}
location / {
try_files $uri $uri/ /index.html;
}
}
这里将页面路由和资源请求分开处理:
- 页面路由找不到实体文件时,返回
index.html,由 Vue Router 接管。 /assets/和指定资源扩展名找不到文件时,直接返回 404。- HTML 要求缓存重新验证;资源先使用短缓存,不急于启用长期不可变缓存。
不能对所有请求统一回退到 index.html。缺失 JS 若收到“200 + HTML”,浏览器仍会报错,而只看状态码的监控可能误认为正常。

若站点已有同域 API,保留其原有 location 和转发行为,不要替换成上述 404 占位块。证书续期若依赖 HTTP 验证路径,也应保留已有处理方式。
3. 检查配置并切换软链接
先执行:
sudo nginx -t
出现证书、语法或重复入口相关错误时,停止切换。确认无误后,再将入口指向本次版本:
sudo ln -s "$RELEASE" /srv/www/vue-app/current.next
sudo mv -Tf /srv/www/vue-app/current.next /srv/www/vue-app/current
sudo nginx -t && sudo systemctl reload nginx
执行前必须确认 current.next 不存在,且 current 是预期软链接。该操作会替换线上入口指向,回滚方法是重新指向记录的上一版目录。临时链接与目标位于同一目录,重命名可避免入口短暂缺失,但不能自动解决旧页面引用旧资源的问题。
使用 reload 而不是 stop/start,可减少不必要的连接中断;reload 后仍须检查服务和日志,不能只凭命令退出状态验收。
四、验证观察:入口、路由和资源分别验收
先直连源站,再验证真实域名链路
下面的 203.0.113.10 是文档示例地址,应替换为香港服务器公网 IP。--resolve 可以固定连接源站,同时保留域名、SNI 和证书校验,不要加 -k。
curl --resolve app.example.com:443:203.0.113.10 \
-sS -D /tmp/vue-home.headers \
-o /tmp/vue-home.html \
https://app.example.com/
curl --resolve app.example.com:443:203.0.113.10 \
-sS -D - -o /dev/null \
https://app.example.com/orders/123
将 /orders/123 替换为实际存在的前端路由。预期首页和 history 路由返回 HTML;但返回 HTML 不代表路由页面正常,还需浏览器直接打开并刷新。
随后去掉 --resolve 再请求,检查实际 DNS、IPv6 和 CDN 链路。如果源站正常、公开域名异常,应排查入口或缓存,而不是反复修改发布目录。
必须请求本次构建引用的真实资源
从 /tmp/vue-home.html 或浏览器 Network 面板复制真实 JS 路径,替换下面示例:
curl --resolve app.example.com:443:203.0.113.10 \
-sS -D - -o /dev/null \
https://app.example.com/assets/index-AbCd1234.js
curl --resolve app.example.com:443:203.0.113.10 \
-sS -D - -o /dev/null \
https://app.example.com/assets/__missing_check__.js
验收应分别判断:
| 检查项 | 预期结果 | 不符合时优先检查 |
|---|---|---|
| 首页与深层路由 | 返回页面,浏览器可渲染 | 域名匹配、路由回退、应用运行错误 |
| 真实 JS、CSS | 200,响应类型正确,内容不是 HTML | 构建路径、文件存在性、MIME 配置 |
| 不存在的 JS | 404 | 是否错误套用 SPA 回退 |
| 图片、字体 | 页面中加载正常 | URL 大小写、路径、跨域响应 |
| 旧浏览器会话 | 页面跳转和懒加载不报资源缺失 | 旧资源保留策略、缓存策略 |
JS 的响应类型应与 JavaScript 相符,CSS 应为 text/css。出现 Unexpected token '<' 时,先查看该资源响应体是否为 HTML,再检查 base、入口目录和 CDN 缓存。403 则优先检查文件读取及目录遍历权限;404 则核对请求 URL 与发布文件是否对应。
浏览器至少验证两种状态:禁用缓存的新会话,以及上线前已打开、上线后再跳转懒加载页面的旧会话。不要只清空缓存后测试,否则可能掩盖新旧资源兼容问题。
用日志确认问题是否持续
sudo tail -n 100 /var/log/nginx/vue-app.error.log
sudo tail -n 100 /var/log/nginx/vue-app.access.log
sudo journalctl -u nginx --since "15 minutes ago" --no-pager
重点观察真实用户请求中的静态资源 404、权限错误、5xx 和请求落错站点的情况。主动验证产生的缺失资源 404 应单独识别。香港机房所在地并不能替代访问验证,还应从主要用户网络测试页面与资源加载;若源站日志没有对应请求,故障可能尚未到达服务器。
五、回滚条件与观察窗口
出现以下任一情况,应停止扩大变更并回滚:
- 真实用户无法打开页面或刷新关键路由。
- 本次 HTML 引用的 JS、CSS 持续 404,或返回 HTML。
- 证书校验失败、请求进入错误站点,且无法在短时间内修复。
- 旧会话集中出现懒加载失败,新旧资源兼容策略失效。
- 错误率明显高于变更前基线,且时间与本次切换吻合。
先恢复入口指向:
PREVIOUS_RELEASE=$(sudo cat "$BACKUP_DIR/previous-release.txt")
sudo test -f "$PREVIOUS_RELEASE/index.html"
sudo ln -s "$PREVIOUS_RELEASE" /srv/www/vue-app/current.rollback
sudo mv -Tf /srv/www/vue-app/current.rollback /srv/www/vue-app/current
确认临时链接不存在、记录目录仍可用后再执行。若问题来自入口配置,还应恢复配置备份:
sudo cp -a "$BACKUP_DIR/vue-app.conf" \
/etc/nginx/sites-available/vue-app.conf
sudo nginx -t && sudo systemctl reload nginx
回滚后重新验证首页、关键路由和上一版真实资源。若存在 CDN 缓存,应按实际策略处理 HTML 及错误缓存;服务器恢复旧目录并不意味着边缘缓存已同步恢复。
本次可安排上线后 30~60 分钟重点观察,并继续覆盖一个正常业务高峰。观察时间是执行建议,不是稳定性保证。窗口内保留上一版目录、配置备份和发布标识,不立即清理旧资源;只有确认入口、关键路由、真实静态资源及旧会话均符合预期,且日志回到可接受基线后,才关闭变更窗口。
本文由A5数据原创发布,转载请注明出处:https://www.a5idc.com/helpcontent/4083.html



