在独立服务器上部署Vue项目,如何配置Nginx支持前端路由刷新?

发布人:A5数据发布时间:2026-11-14 10:52阅读量:42

在独立服务器上部署 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。正确的处理方式是:

横向简洁流程图,从浏览器发起请求开始,分成嵌套路由、存在的静态资源、缺失的静态资源三条路径;展示 Nginx 检查文件、回退到 Vue 入口或返回 404 的结

  1. 如果请求对应真实文件,例如 JavaScript、CSS、图片,直接返回文件。
  2. 如果请求不是服务器上的真实文件,将请求交给 index.html。
  3. 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,出现问题时可以切回上一版本。

上传 Vue 构建文件并创建发布目录 / 使用独立发布目录配图

先在服务器上创建目录:

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 文件名一致。

在浏览器中进行最终验证

使用域名访问后,按以下顺序检查:

  1. 打开首页,确认 Vue 页面能够正常渲染。
  2. 点击导航进入一个嵌套路由。
  3. 复制当前地址,在新标签页中直接打开。
  4. 在该路由页面按浏览器刷新。
  5. 打开开发者工具的 Network 面板,确认 index.html、JS、CSS 和图片没有异常状态码。
  6. 查看 Console 面板,确认没有 Failed to load module script、资源 404 或基础路径错误。
  7. 如果项目有前端 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

相关推荐