Vue 项目布署后，刷新页面（或跳转页面）出现 404 解决办法_vue 刷新页面报错404

问题背景

今天重新部署一个vue项目的时候，发现在刷新页面和请求跳转其他页面（非跟页面，也就是 /index.html）出现 404 错误。

为什么会出现404

看一下打包的 dist 文件

可以看到dist下只有一个 index.html 文件及一些静态资源，这个是因为Vue是单页应用(SPA)，只有一个index.html作为入口文件，其它的路由都是通过JS来进行跳转

接下来看一下服务器的配置，以 nginx 为例

server {
  // 监听80端口
  listen 80;
  // 定义你的站点名称
  server_name website.com;
  // 根据请求 URI 设置配置
  location / {
      // 站点根目录，这里为 vue 构建出来的 dist 目录
      root   /www/dist;
      // 站点初始页为index.html 或 index.htm
      index  index.html index.htm;
  }
}
1
2
3
4
5
6
7
8
9
10
11
12
13

我们现在可以根据 nginx 配置得出，当我们在地址栏输入 website.com 时，这时会打开我们 dist 目录下的 index.html 文件，然后我们在跳转路由进入到 website.com/login

关键在这里，当我们在 website.com/login 页执行刷新操作，nginx location 是没有相关配置的，所以就会出现 404 的情况

为什么hash模式下没有问题

router hash 模式我们都知道是用符号#表示的，如 website.com/#/login, hash 的值为 #/login

它的特点在于：hash 虽然出现在 URL 中，但不会被包括在 HTTP 请求中，对服务端完全没有影响，因此改变 hash 不会重新加载页面

hash 模式下，仅 hash 符号之前的内容会被包含在请求中，如 website.com/#/login 只有 website.com 会被包含在请求中 ，因此对于服务端来说，即使没有配置location，也不会返回404错误

解决办法（两种）

方法一：改变服务器配置

vue-router 官网地址

Apache

<IfModule mod_negotiation.c>
  Options -MultiViews
</IfModule>

<IfModule mod_rewrite.c>
  RewriteEngine On
  RewriteBase /
  RewriteRule ^index\.html$ - [L]
  RewriteCond %{REQUEST_FILENAME} !-f
  RewriteCond %{REQUEST_FILENAME} !-d
  RewriteRule . /index.html [L]
</IfModule>
1
2
3
4
5
6
7
8
9
10
11
12

也可以使用 FallbackResource 代替 mod_rewrite。

nginx

location / {
  try_files $uri $uri/ /index.html;
}
1
2
3

原生 Node.js

const http = require('http')
const fs = require('fs')
const httpPort = 80

http
  .createServer((req, res) => {
    fs.readFile('index.html', 'utf-8', (err, content) => {
      if (err) {
        console.log('We cannot open "index.html" file.')
      }

      res.writeHead(200, {
        'Content-Type': 'text/html; charset=utf-8',
      })

      res.end(content)
    })
  })
  .listen(httpPort, () => {
    console.log('Server listening on: http://localhost:%s', httpPort)
  })
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

Express + Node.js

对于 Node.js/Express，可以考虑使用 connect-history-api-fallback 中间件。

Internet Information Services (IIS)

1. 安装 IIS UrlRewrite
2. 在网站的根目录下创建一个 web.config 文件，内容如下：

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
  <system.webServer>
    <rewrite>
      <rules>
        <rule name="Handle History Mode and custom 404/500" stopProcessing="true">
          <match url="(.*)" />
          <conditions logicalGrouping="MatchAll">
            <add input="{REQUEST_FILENAME}" matchType="IsFile" negate="true" />
            <add input="{REQUEST_FILENAME}" matchType="IsDirectory" negate="true" />
          </conditions>
          <action type="Rewrite" url="/" />
        </rule>
      </rules>
    </rewrite>
  </system.webServer>
</configuration>
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

Caddy v2

try_files {path} /
1

Caddy v1

rewrite {
    regexp .*
    to {path} /
}
1
2
3
4

Firebase hosting

将此添加到你的 firebase.json 中：

{
  "hosting": {
    "public": "dist",
    "rewrites": [
      {
        "source": "**",
        "destination": "/index.html"
      }
    ]
  }
}
1
2
3
4
5
6
7
8
9
10
11

Netlify

创建一个 _redirects 文件，包含在你的部署文件中：

/* /index.html 200
1

在 vue-cli、nuxt 和 vite 项目中，这个文件通常放在名为 static 或 public 的目录下。

你可以在 Netlify 文档中找到更多关于语法的信息。你也可以创建一个 netlify.toml 来结合其他 Netlify 功能的重定向。

Vercel

在项目根目录创建一个vercel.json文件，内容如下：

{
  "rewrites": [{ "source": "/:path*", "destination": "/index.html" }]
}
1
2
3

Caveat

这有一个注意事项。你的服务器将不再报告 404 错误，因为现在所有未找到的路径都会显示你的 index.html 文件。为了解决这个问题，你应该在你的 Vue 应用程序中实现一个万能的路由来显示 404 页面。

const router = createRouter({
  history: createWebHistory(),
  routes: [{ path: '/:pathMatch(.*)', component: NotFoundComponent }],
})
1
2
3
4

方法二：改变路由模式

Hash 模式

hash 模式是用 createWebHashHistory() 创建的：

import { createRouter, createWebHashHistory } from 'vue-router'

const router = createRouter({
  history: createWebHashHistory(),
  routes: [
    //...
  ],
})
1
2
3
4
5
6
7
8

它在内部传递的实际 URL 之前使用了一个哈希字符（#）。由于这部分 URL 从未被发送到服务器，所以它不需要在服务器层面上进行任何特殊处理。不过，它在 SEO 中确实有不好的影响。如果你担心这个问题，可以使用 HTML5 模式。

HTML5 模式

用 createWebHistory() 创建 HTML5 模式，推荐使用这个模式：

import { createRouter, createWebHistory } from 'vue-router'

const router = createRouter({
  history: createWebHistory(),
  routes: [
    //...
  ],
})
1
2
3
4
5
6
7
8

当使用这种历史模式时，URL 会看起来很 “正常”，例如 https://example.com/user/id。漂亮!

不过，问题来了。由于我们的应用是一个单页的客户端应用，如果没有适当的服务器配置，用户在浏览器中直接访问 https://example.com/user/id，就会得到一个 404 错误。这就尴尬了。

不用担心：要解决这个问题，你需要做的就是在你的服务器上添加一个简单的回退路由。如果 URL 不匹配任何静态资源，它应提供与你的应用程序中的 index.html 相同的页面。漂亮依旧!

因为我其他地方用到了重定向以及要取得上一个页面的地址，所以没有办法用 hash 模式，所以直接修改的服务器配置。
若没有我这样的限制的话，直接将路由模式改为 hash 即可。

单页应用(SPA)概念

单页应用

单页应用（single-page application），缩写SPA 是一种网络应用程序或网站的模型，它通过动态重写当前页面来与用户交互，而非传统的从服务器重新加载整个新页面。这种方法避免了页面之间切换打断用户体验，使应用程序更像一个桌面应用程序。在单页应用中，所有必要的代码（HTML、JavaScript和CSS）都通过单个页面的加载而检索，或者根据需要（通常是为响应用户操作）动态装载适当的资源并添加到页面。尽管可以用位置散列或HTML5历史API来提供应用程序中单独逻辑页面的感知和导航能力，但页面在过程中的任何时间点都不会重新加载，也不会将控制转移到其他页面

大白话来讲：

一个杯子，早上装的牛奶，中午装的是开水，晚上装的是茶，我们可以发现，变的始终是内容，而容器还是那个容器

当然，每种技术都有其利弊，单页应用也是如此

利:

1. 无刷新体验，这个应该是最显著的有点，由于路由分发直接在浏览器端完成，页面是不刷新，对用户的响应非常及时，因此提升了用户体验

2. 完全的前端组件化，前端开发不再以页面为单位，更多地采用组件化的思想，代码结构和组织方式更加规范化，便于修改和调整

弊:

1. 首屏较长，要在一个页面上为用户提供产品的所有功能，在这个页面加载的时候，首先要加载大量的静态资源，这个加载时间相对比较长

2. 不利于 SEO，单页页面，数据在前端渲染，就意味着没有 SEO，或者需要使用变通的方案