React+Vite项目部署Railway后路由刷新404问题求助

核心原因 #

SPA的客户端路由仅在浏览器端处理，刷新子路由时，服务端会尝试寻找对应路径的物理文件，找不到就返回404。解决思路是让服务端将所有路由请求都返回index.html，交由React Router处理客户端路由逻辑。

方案1：静态站点部署（推荐） #

步骤1：确认Vite构建配置 #

在vite.config.js中确保build输出目录为dist（Vite默认配置即为该目录，可省略），示例配置：

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

export default defineConfig({
  plugins: [react()],
  build: {
    outDir: 'dist' // 输出目录，默认值可省略
  }
})

步骤2：配置Railway路由重写 #

在项目根目录创建railway.toml文件，添加重写规则，让所有非静态资源的请求都指向index.html：

[[rewrites]]
source = "/*"
destination = "/index.html"

Railway会自动识别该配置，部署后刷新子路由即可正常加载页面。

方案2：自定义Node.js服务（适用于需要后端逻辑的场景） #

步骤1：安装依赖 #

npm install express

步骤2：创建服务器文件 #

在项目根目录新建server.js：

const express = require('express')
const path = require('path')
const app = express()

// 托管dist目录下的静态资源
app.use(express.static(path.join(__dirname, 'dist')))

// 所有路由请求返回index.html
app.get('*', (req, res) => {
  res.sendFile(path.join(__dirname, 'dist', 'index.html'))
})

const PORT = process.env.PORT || 3000
app.listen(PORT, () => {
  console.log(`Server running on port ${PORT}`)
})

步骤3：修改启动命令 #

在package.json中更新start命令：

{
  "scripts": {
    "dev": "vite",
    "build": "vite build",
    "start": "node server.js"
  }
}

Railway部署时会自动执行npm start，通过自定义服务处理路由 fallback。

常见疑问解答 #

• 是否需要迁移到Webpack？
  不需要。Vite完全支持SPA路由部署，Webpack的devServer.historyApiFallback是开发环境的配置，生产部署的核心逻辑都是让服务端返回index.html，上述Vite方案可完全实现该需求。

• 是Railway平台的问题吗？
  不是。这是SPA路由的通用问题，任何静态服务器部署SPA都会遇到，Railway提供了重写规则和自定义服务的支持，配置正确即可解决。

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