在独立服务器上部署Vue项目,如何配置Nginx支持前端路由刷新?
在独立服务器上部署 Vue 单页应用时,前端路由刷新失败通常不是 Vue 组件的问题,而是 Nginx 将 /users/1001、/dashboard 这类路由当成了服务器上的真实文件。使用 Vue Router 的 history 模式后,Nginx 找不到对应文件时,必须将请求回退到 index.html,再由 Vue Router 根据当前路径渲染页面。
下面以 Ubuntu 22.04/24.04、Nginx、Vue 3 + Vite、网站部署在域名根路径为例。示例假设域名为 app.example.com,项目构建产物目录为 dist,服务器上的站点目录为 /var/www/vue-site。命令和配置中的域名、服务器地址、发布版本号需要替换成实际值。
先确定前端路由模式
history 模式为什么需要 Nginx 配合
Vue Router 常见的两种路由模式如下:
import { createRouter, createWebHistory } from 'vue-router'
const router = createRouter({
history: createWebHistory(import.meta.env.BASE_URL),
routes: [
// 路由配置
]
})
export default router
createWebHistory() 生成的地址类似:
https://app.example.com/dashboard
https://app.example.com/users/1001
当用户从首页点击进入 /dashboard 时,浏览器已经加载了 index.html,后续由 Vue Router 接管路由。但用户直接访问或刷新 /dashboard 时,浏览器会先向 Nginx 请求这个路径。
如果服务器目录中没有:
/var/www/vue-site/current/dashboard
Nginx 默认可能返回 404。正确的处理方式是:

- 如果请求对应真实文件,例如 JavaScript、CSS、图片,直接返回文件。
- 如果请求不是服务器上的真实文件,将请求交给
index.html。 - Vue 应用加载后,再由 Vue Router 判断当前路径应该渲染哪个页面。
Nginx 中实现这个逻辑的关键配置是:
try_files $uri $uri/ /index.html;
如果项目使用的是 createWebHashHistory(),地址会带有 #,例如:
https://app.example.com/#/dashboard
# 后面的内容不会作为 HTTP 路径发送给服务器,因此通常不依赖 Nginx 回退。但这种地址结构与 history 模式不同,不能通过简单修改 Nginx 配置将两种模式混用。
本文使用的环境边界
| 项目 | 示例值 |
|---|---|
| 操作系统 | Ubuntu 22.04/24.04 |
| Web 服务 | Nginx |
| 前端框架 | Vue 3 |
| 构建工具 | Vite |
| 路由模式 | createWebHistory() |
| 构建目录 | dist |
| 部署路径 | /var/www/vue-site/current |
| 访问方式 | 域名根路径,例如 https://app.example.com/ |
如果项目使用 Vue CLI,通常也会生成 dist 目录,Nginx 的处理方式基本相同。需要重点核对的是构建命令、静态资源目录和前端资源基础路径。
部署前检查项目和构建产物
检查服务器和域名条件
开始操作前,应确认以下条件已经具备:
- 可以通过 SSH 登录服务器,并拥有
sudo权限。 - 域名的 A 记录已经指向服务器 IPv4 地址。
- 如果配置了 IPv6,AAAA 记录也应指向正确地址。
- 云服务器安全组或系统防火墙允许 TCP 80 端口访问。
- 项目已经确定使用根路径部署,而不是
/portal/、/admin/等子目录。 - 已经确认项目的 Node.js 版本要求。
可以先在服务器上检查系统和网络服务条件:
cat /etc/os-release
sudo ss -lntp | grep -E ':80|:443' || true
如果 80 端口暂时没有服务监听,不代表配置错误,后续启动 Nginx 后再验证即可。若已有其他网站占用 80 端口,应先确认是否可以复用现有 Nginx,而不是直接覆盖原有配置。
核对 Vite 的基础路径
部署到域名根路径时,Vite 配置通常应使用 /:
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
export default defineConfig({
plugins: [vue()],
base: '/'
})
如果项目没有显式配置 base,Vite 默认也通常按根路径处理。但如果项目此前部署在子目录,配置中可能存在:
base: '/portal/'
此时直接复制到域名根路径,页面可能能够打开,但 JavaScript 和 CSS 会请求错误的地址。部署位置变化后,应同步调整 base,然后重新构建。
构建并检查 dist
建议先在开发机或构建机完成编译,服务器只负责提供静态文件。这样可以减少服务器上的 Node.js 版本、依赖安装和构建权限问题。
在项目根目录执行:
node --version
npm --version
npm ci
npm run build
如果项目没有 package-lock.json,可以根据项目实际情况使用:
npm install
npm run build
构建完成后检查输出目录:
test -f dist/index.html && echo "index.html exists"
find dist -maxdepth 2 -type f | head -n 20
du -sh dist
预期可以看到 index.html 和静态资源文件,例如:
index.html
assets/index-xxxxxxxx.js
assets/index-xxxxxxxx.css
这里的文件名只是示例,不同构建结果会有所变化。只要 dist/index.html 存在,并且资源文件位于构建目录内即可。
如果项目必须在服务器上构建,应先确认服务器上的 Node.js 版本满足 package.json 中的 engines 要求,再执行相同的 npm ci 和 npm run build。不建议因为构建失败而随意更换 Node.js 主版本,否则可能引入依赖兼容问题。
对于需要将 Vue 前端部署在独立服务器上的企业,A5idc数据提供中国香港、美国、日本、韩国、中国台湾、新加坡和马来西亚等地区的物理服务器租用,覆盖常规建站、AMD 计算、NVMe 存储及不同带宽线路,可为网站前端、业务后台、数据库和接口服务提供独立的 CPU、内存、磁盘与网络资源基础,支持搭建相应的 Nginx 发布环境。
安装并启动 Nginx
在 Ubuntu 系统上执行:
sudo apt update
sudo apt install -y nginx rsync
sudo nginx -v
sudo systemctl enable --now nginx
sudo systemctl is-active nginx
如果输出:
active
说明 Nginx 服务已经启动。此时直接访问服务器 IP,通常会看到 Nginx 默认页面,这只代表服务进程正常运行,还没有代表 Vue 项目配置完成。
Ubuntu 默认使用:
/etc/nginx/sites-available/
/etc/nginx/sites-enabled/
如果使用的是 AlmaLinux、Rocky Linux 等发行版,常见配置目录可能是:
/etc/nginx/conf.d/
这两种方式不能同时照搬。可以通过以下命令查看主配置实际加载了哪些文件:
sudo nginx -T 2>/dev/null | head -n 40
上传 Vue 构建文件并创建发布目录
使用独立发布目录
不建议直接把文件复制到 Nginx 正在使用的目录中。首次部署也可以采用发布目录加 current 软链接的方式:
/var/www/vue-site/
├── current -> releases/release-001
└── releases/
└── release-001/
├── index.html
└── assets/
这样后续发布新版本时,只需要新增一个目录并切换 current,出现问题时可以切回上一版本。

先在服务器上创建目录:
sudo install -d -m 0755 /var/www/vue-site
sudo install -d -m 0755 /var/www/vue-site/releases
上传构建产物
在本地项目目录执行。下面的 deploy、SERVER_IP 和发布目录名称需要替换:
rsync -az --delete dist/ deploy@SERVER_IP:/tmp/vue-dist-release-001/
--delete 只用于清理临时上传目录,确保临时目录与本次 dist 内容一致。执行前必须确认目标是 /tmp/vue-dist-release-001/,不要将该参数用于 /var/www/vue-site/current/ 或正在使用的发布目录。
如果本地没有 rsync,也可以使用:
scp -r dist/. deploy@SERVER_IP:/tmp/vue-dist-release-001/
使用 scp 时,应确认临时目录中没有上一次构建遗留的旧文件。
登录服务器后,将临时文件复制到新的发布目录:
RELEASE=release-001
sudo install -d -m 0755 "/var/www/vue-site/releases/$RELEASE"
sudo cp -a /tmp/vue-dist-release-001/. "/var/www/vue-site/releases/$RELEASE/"
sudo find "/var/www/vue-site/releases/$RELEASE" -type d -exec chmod 755 {} \;
sudo find "/var/www/vue-site/releases/$RELEASE" -type f -exec chmod 644 {} \;
sudo ln -sfn "/var/www/vue-site/releases/$RELEASE" /var/www/vue-site/current
上面的权限调整只作用于本次发布目录,目的是保证 Nginx 可以进入目录并读取文件,不会修改整台服务器的权限。
检查发布结果:
test -f /var/www/vue-site/current/index.html && echo "index.html exists"
readlink -f /var/www/vue-site/current
find /var/www/vue-site/current -maxdepth 2 -type f | head -n 20
预期结果中,readlink -f 应指向:
/var/www/vue-site/releases/release-001
如果找不到 index.html,不要继续配置 Nginx,应先检查本地构建目录和上传路径。
配置 Nginx 的前端路由回退
创建站点配置
首次创建配置前,如果同名文件已经存在,应先备份。以下命令不会影响其他 Nginx 站点:
if [ -f /etc/nginx/sites-available/vue-site ]; then
sudo cp -a /etc/nginx/sites-available/vue-site \
"/etc/nginx/sites-available/vue-site.bak.$(date +%Y%m%d%H%M%S)"
fi
创建配置文件:
sudo tee /etc/nginx/sites-available/vue-site >/dev/null <<'NGINX'
server {
listen 80;
listen [::]:80;
server_name app.example.com;
root /var/www/vue-site/current;
index index.html;
include /etc/nginx/mime.types;
location / {
try_files $uri $uri/ /index.html;
}
location ~* \.(?:js|mjs|css|png|jpg|jpeg|gif|svg|ico|webp|avif|woff|woff2|ttf)$ {
try_files $uri =404;
access_log off;
}
location = /index.html {
add_header Cache-Control "no-cache" always;
}
}
NGINX
需要将 app.example.com 替换为实际域名。配置中的关键部分有三个:
root /var/www/vue-site/current;
指定 Nginx 从哪个目录读取构建产物。使用 current 软链接后,切换发布版本时不需要修改 Nginx 配置。
try_files $uri $uri/ /index.html;
先查找真实文件或目录,找不到时回退到 index.html。这正是 history 模式能够刷新页面的核心。
try_files $uri =404;
这条规则用于 JavaScript、CSS 和图片等静态资源。资源路径写错时返回 404,而不是错误地返回 Vue 的 index.html。如果缺失的 JavaScript 也返回 HTML,浏览器可能会报 MIME 类型错误,问题定位会更困难。
启用配置并检查语法
执行:
sudo ln -sfn /etc/nginx/sites-available/vue-site \
/etc/nginx/sites-enabled/vue-site
sudo nginx -t
预期输出类似:
syntax is ok
test is successful
只有语法检查通过后才重新加载:
sudo systemctl reload nginx
sudo systemctl is-active nginx
这里使用 reload 而不是直接 restart,可以减少配置变更对现有连接的影响。如果 nginx -t 失败,不要执行 reload,应先根据错误提示修正配置;当前已经运行的旧配置通常仍然保持生效。
如果服务器上没有 sites-enabled 机制,可以将配置写入:
/etc/nginx/conf.d/vue-site.conf
然后执行相同的 nginx -t 和 reload 流程。
按请求链路验证部署结果
在服务器本机验证首页
如果 DNS 尚未生效,可以通过 Host 请求头在服务器本机测试指定站点:
curl -sS -o /dev/null \
-w 'home status: %{http_code}\n' \
-H 'Host: app.example.com' \
http://127.0.0.1/
预期输出:
home status: 200
进一步检查响应类型:
curl -sSI \
-H 'Host: app.example.com' \
http://127.0.0.1/ | grep -Ei 'HTTP/|Content-Type|Cache-Control'
首页通常应返回 text/html。
验证嵌套路由刷新
选择项目中真实存在的一条前端路由,例如 /dashboard:
curl -sS -o /dev/null \
-w 'dashboard status: %{http_code}\n' \
-H 'Host: app.example.com' \
http://127.0.0.1/dashboard
如果项目中有动态路由,也可以使用:
curl -sS -o /dev/null \
-w 'detail status: %{http_code}\n' \
-H 'Host: app.example.com' \
http://127.0.0.1/users/1001
预期状态码为 200。为了确认这不是某个静态文件,而是回退到了 Vue 入口文件,可以检查响应内容:
curl -sS \
-H 'Host: app.example.com' \
http://127.0.0.1/dashboard | head -n 20
返回内容中通常可以看到 index.html 的根节点,例如:
<div id="app"></div>
这表示 Nginx 已经将嵌套路由交给 Vue 应用处理。页面最终显示哪个组件,则由 Vue Router 的路由表决定。
验证静态资源
从 index.html 中找到一条 JavaScript 或 CSS 路径后检查:
curl -sSI \
-H 'Host: app.example.com' \
http://127.0.0.1/assets/index-xxxxxxxx.js
静态资源应返回 200,并带有 JavaScript 或 CSS 类型。如果资源返回 404,需要检查:
root是否指向了正确的发布目录。- Vite 的
base是否与部署位置一致。 - 构建文件是否完整上传。
- 请求路径中的大小写是否与 Linux 文件名一致。
在浏览器中进行最终验证
使用域名访问后,按以下顺序检查:
- 打开首页,确认 Vue 页面能够正常渲染。
- 点击导航进入一个嵌套路由。
- 复制当前地址,在新标签页中直接打开。
- 在该路由页面按浏览器刷新。
- 打开开发者工具的 Network 面板,确认
index.html、JS、CSS 和图片没有异常状态码。 - 查看 Console 面板,确认没有
Failed to load module script、资源 404 或基础路径错误。 - 如果项目有前端 404 页面,访问一个不存在的业务路径,确认由 Vue 的 NotFound 组件处理。
如果希望前端自行显示 404 页面,可以在 Vue Router 中配置兜底路由:
const routes = [
{
path: '/:pathMatch(.*)*',
component: () => import('@/views/NotFound.vue')
}
]
需要注意,Nginx 的 try_files 只负责将非文件请求交给 index.html,它并不知道某个业务路径是否存在。业务层面的 404 由 Vue Router 负责。
常见异常和处理方法
刷新嵌套路由仍然返回 404
先查看当前运行的配置是否真的包含回退规则:
sudo nginx -T 2>/dev/null | grep -nE 'server_name|root|try_files'
如果没有看到目标域名对应的:
try_files $uri $uri$ /index.html;
应检查以下项目:
- 修改的是不是实际加载的配置文件。
server_name是否与访问域名一致。- 是否忘记执行
sudo nginx -t和 reload。 - 请求是否被另一个
server配置接收。 root是否指向了当前发布目录。
如果使用 IP 直接访问,而 Nginx 配置只写了域名,测试时可能会命中默认站点。可以先使用域名访问,或者通过 Host 请求头验证。
首页显示 Nginx 默认页面
这通常表示请求没有命中 Vue 站点配置。检查 DNS 和 Nginx 配置:
getent hosts app.example.com
sudo nginx -T 2>/dev/null | grep -n 'server_name'
然后确认浏览器访问的域名和配置中的 server_name 完全一致,包括是否带有 www。不要在没有确认其他站点用途的情况下直接删除默认配置,因为同一台服务器上可能还有其他网站依赖它。
页面状态码为 200,但浏览器白屏
优先检查浏览器 Network 面板中的 JavaScript 请求。如果 JS 路径带有错误的目录前缀,例如项目部署在根路径,却请求了:
/portal/assets/index-xxxx.js
通常是 base 配置与实际部署路径不一致。
根路径部署时应重新确认:
export default defineConfig({
base: '/'
})
修改配置后必须重新执行:
npm run build
然后上传新的 dist 并切换发布版本。只 reload Nginx 不会改变已经生成的 JavaScript 引用路径。
JavaScript 请求返回 HTML
如果开发者工具提示类似“模块脚本的 MIME 类型不正确”,可以检查:
curl -sSI -H 'Host: app.example.com' \
http://127.0.0.1/assets/index-xxxxxxxx.js
如果状态码是 200,但内容类型为 text/html,说明静态资源没有被正确匹配,可能是:
root目录错误。- 资源文件没有上传。
- Nginx 配置中缺少静态资源的
try_files $uri =404。 - 构建时
base指向了错误的路径。
返回 403 Forbidden
先检查路径中每一级目录和文件的权限:
namei -l /var/www/vue-site/current/index.html
ls -ld /var/www/vue-site
ls -ld /var/www/vue-site/releases
ls -l /var/www/vue-site/current/index.html
Nginx 需要能够进入父目录,并读取 index.html 及其静态资源。权限修复应限制在站点发布目录内,不要对 /、/var 或整个系统执行递归权限修改。
页面仍然显示旧版本
可以先查看当前软链接指向:
readlink -f /var/www/vue-site/current
再检查首页缓存策略:
curl -sSI -H 'Host: app.example.com' \
http://127.0.0.1/index.html | grep -i cache
配置中的 Cache-Control: no-cache 会让浏览器重新验证入口文件。带哈希的 JS 和 CSS 可以使用较长缓存,但 index.html 不应长期缓存,否则新版本的入口文件可能仍引用旧资源。
如果项目启用了 PWA 或 Service Worker,还需要在浏览器开发者工具的 Application 面板检查 Service Worker 和缓存状态。Service Worker 的更新策略应由项目自身版本管理,不能只依赖 Nginx reload。
API 请求被返回了 index.html
如果同一域名还承载 API,请避免让 /api/ 请求落入通用的前端回退规则。否则接口路径不存在时,Nginx 可能把 Vue 的 index.html 返回给接口调用方。
应为 API 单独配置匹配规则,再让其他路径进入 Vue 回退。例如:
location /api/ {
proxy_pass http://127.0.0.1:3000;
}
location / {
try_files $uri $uri/ /index.html;
}
其中后端地址、请求头和超时参数应按实际服务配置。没有后端服务时,不要直接添加这段反向代理配置。
验收与回滚检查项
上线验收
确认以下项目全部通过后,再清理临时文件或旧版本:
sudo nginx -t返回语法检查成功。- Nginx 服务状态为
active。 - 首页请求返回
200。 - 至少一条嵌套路由直接访问返回
200。 - 在嵌套路由页面刷新后仍然能够渲染。
- JS、CSS、图片等静态资源没有 404。
- 静态资源返回正确的内容类型。
readlink -f /var/www/vue-site/current指向本次发布目录。- 浏览器 Console 没有基础路径、模块加载或运行时异常。
- Nginx 错误日志没有持续新增异常:
sudo tail -n 50 /var/log/nginx/error.log
sudo tail -n 50 /var/log/nginx/access.log
应用版本回滚
如果新版本出现白屏、资源缺失或路由异常,优先回滚 current 软链接,不要立即删除当前发布目录。假设上一版本目录为 release-000:
sudo ln -sfn \
/var/www/vue-site/releases/release-000 \
/var/www/vue-site/current
sudo nginx -t && sudo systemctl reload nginx
readlink -f /var/www/vue-site/current
静态文件内容没有变化时,切换软链接后通常不需要重启 Nginx。回滚后重新执行首页、嵌套路由和资源请求检查。
Nginx 配置回滚
如果问题由 Nginx 配置变更引起,可以恢复此前的备份文件:
sudo cp -a /etc/nginx/sites-available/vue-site.bak.YYYYMMDDHHMMSS \
/etc/nginx/sites-available/vue-site
sudo nginx -t && sudo systemctl reload nginx
如果备份文件本身不确定,应先列出可用备份:
ls -lt /etc/nginx/sites-available/vue-site.bak.*
回滚的判断标准是:原有站点能恢复访问、Vue 首页能够加载、嵌套路由刷新不再返回 404。确认新版本和新配置稳定后,再根据保留周期清理旧发布目录和临时上传目录,避免误删仍用于回滚的版本。
本文由A5数据原创发布,转载请注明出处:https://www.a5idc.com/helpcontent/9359.html



