部署Vite SSR React项目至Vercel时出现404页面未找到错误

核心问题分析 #

本地开发、构建预览都正常，但Vercel部署后出现404，大概率是部署配置未匹配Vite SSR的产物结构，或是缺少服务端请求路由的兜底配置。

1. 核对Build Command与Output Directory #

• 先确认vite.config.ts里的构建输出目录，比如默认配置：

  export default defineConfig({
    build: {
      outDir: 'dist', // 该目录需和Vercel设置完全一致
      ssr: true,
    },
    // 其他SSR相关配置
  })
  

• 在Vercel部署设置中，将Output Directory改为与outDir一致的路径（比如dist）；Build Command保持npm run build即可，无需修改。

2. 添加Vercel路由与函数配置 #

Vite SSR依赖服务端入口处理所有请求，仅部署静态文件会导致404。在项目根目录创建vercel.json，配置如下：

{
  "functions": {
    "server.js": { // 替换为你的服务端入口文件路径，比如src/server.js
      "runtime": "@vercel/node@20"
    }
  },
  "routes": [
    {
      "src": "/(.*)",
      "dest": "/server.js"
    }
  ]
}

• 确保服务端入口文件正确处理静态资源与SSR渲染，示例逻辑：

  import express from 'express';
  import fs from 'fs';
  import path from 'path';
  
  const app = express();
  const distPath = path.resolve(__dirname, 'dist/client');
  app.use(express.static(distPath));
  
  app.get('*', (req, res) => {
    // 读取生产环境HTML模板
    const template = fs.readFileSync(path.resolve(distPath, 'index.html'), 'utf-8');
    // 插入你的SSR渲染逻辑，比如将React组件渲染结果注入模板
    res.send(template);
  });
  
  export default app;
  

3. 不要修改Development Command #

该配置仅用于Vercel的开发环境预览，和生产部署无关，改它无法解决404问题，保持默认或设为npm run dev即可。

4. 查看部署日志定位细节 #

如果以上配置都没问题，进入Vercel部署详情页查看日志，排查是否存在文件缺失、路径错误或服务端入口执行失败的提示，日志中的报错信息能快速定位问题。

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