Vite部署React项目后刷新页面出现404问题求助

问题现象 #

使用React+Vite构建的单页应用（SPA），页面内部跳转功能正常，但部署到服务器（包括Vite预览服务器或第三方服务器）后，刷新特定路径（如/products/123）或直接在浏览器地址栏输入该路径时，会出现404页面。本地运行yarn run dev时一切正常，刷新和直接输入URL均无问题。

相关配置 #

路由配置（react-router-dom v5）

<Switch>
    <Route path="/products/:id" component={ProductView}></Route>
    <Route path="/home" component={Home}></Route>
    <Route path="/contact" component={Contact}></Route>
    <Route path="/not-found" component={NotFound}></Route>
    <Redirect path="/" exact to="/home" />
    <Redirect path="" exact to="/home" />
</Switch>

vite.config.js配置

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'

export default defineConfig({
  plugins: [react({
    include: "**/*.jsx",
  })]
})

依赖版本

"react": "^17.0.1",
"react-dom": "^17.0.1",
"react-router-dom": "^5.2.0",

已尝试但无效的方案 #

• 升级react-router到v6版本
• 添加200.html页面
• 为路由添加通配符规则

核心原因 #

SPA的路由逻辑由前端JavaScript接管，服务器默认会将URL路径当作静态文件路径去查找对应的资源。当用户刷新或直接输入/products/123这类路径时，服务器找不到对应的文件，就会返回404。Vite本身没有默认配置支持SPA路由的 fallback 机制，需要服务器配合将所有路由请求转发到index.html，再由前端路由处理。

解决方案 #

方案1：Docker+Nginx部署（推荐） #

通过Docker打包应用，使用Nginx配置路由 fallback，确保所有请求都转发到index.html。

1. 编写Dockerfile

FROM node:14-alpine AS builder

ARG YOUR_ENVIRONMENT_VARIABLES
ARG YOUR_ENVIRONMENT_VARIABLES

# 设置工作目录
WORKDIR /app

COPY package.json .

RUN yarn install

COPY . /app/

RUN yarn build

FROM nginx:alpine

# 切换到Nginx静态资源目录
WORKDIR /usr/share/nginx/html

# 删除默认静态资源
RUN rm -rf ./*

# 复制构建产物
COPY --from=builder /app/dist .

# 复制自定义Nginx配置
COPY .nginx/nginx.conf /etc/nginx/conf.d/default.conf

ENTRYPOINT ["nginx", "-g", "daemon off;"]

2. 创建Nginx配置文件
   在项目根目录新建.nginx文件夹，创建nginx.conf文件，内容如下：

server {
    listen 80;
    server_name localhost;

    root /usr/share/nginx/html;
    index index.html;

    # 所有请求转发到index.html，由前端路由处理
    location / {
        try_files $uri $uri/ /index.html;
    }

    # 处理静态资源缓存
    location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg)$ {
        expires 1y;
        add_header Cache-Control "public, immutable";
    }
}

3. 构建并运行Docker镜像

# 构建镜像
docker build -t your-app-name .

# 运行容器
docker run -p 80:80 your-app-name

方案2：直接配置Nginx部署 #

如果不使用Docker，直接将Vite构建后的dist目录部署到Nginx，只需修改Nginx的站点配置，添加try_files $uri $uri/ /index.html;规则即可，配置参考方案1中的nginx.conf。

方案3：配置Vite预览服务器 #

如果使用vite preview启动预览服务器，可在vite.config.js中添加preview配置，开启history fallback：

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'

export default defineConfig({
  plugins: [react({
    include: "**/*.jsx",
  })],
  preview: {
    historyApiFallback: true, // 开启SPA路由 fallback
  }
})

这样运行vite preview时，刷新或直接输入路径就不会出现404了。

内容的提问来源于stack exchange，提问作者codebear22