如何配置Vite的dev server使其对不存在的路径返回404错误

原因说明 #

你遇到的情况是Vite默认开启了SPA（单页应用）回退机制导致的：为了支持前端客户端路由的正常使用，所有匹配不到静态资源的请求，都会默认返回根目录下的index.html内容，状态码为200。

解决方案 #

方案1：完全关闭开发环境SPA回退 #

直接修改vite.config.js（或vite.config.ts）的server.spaFallback配置项为false即可，访问不存在的路径时会直接返回404：

import { defineConfig } from 'vite'

export default defineConfig({
  server: {
    // 关闭开发服务器的SPA自动回退逻辑
    spaFallback: false
  },
  // 如果使用vite preview预览构建产物时也需要相同效果，添加以下配置
  preview: {
    spaFallback: false
  }
})

方案2：自定义规则控制404返回（灵活场景） #

如果不需要完全关闭SPA回退，仅希望特定路径（比如所有.html后缀的请求）不存在时返回404，可以通过Vite插件自定义中间件实现：

import { defineConfig } from 'vite'
import fs from 'fs/promises'
import path from 'path'

export default defineConfig({
  plugins: [
    {
      name: 'custom-404-handler',
      configureServer(server) {
        server.middlewares.use(async (req, res, next) => {
          // 可自行修改匹配规则，这里示例匹配所有.html结尾的请求
          if (req.url?.endsWith('.html')) {
            const targetPath = path.join(server.config.root, req.url.split('?')[0])
            try {
              await fs.access(targetPath)
            } catch (err) {
              // 文件不存在时返回404
              res.statusCode = 404
              res.end('404 Not Found')
              return
            }
          }
          next()
        })
      }
    }
  ]
})

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