Remix应用部署至Vercel后仅首页可加载，其他路由报404求助

1. 配置官方Remix-Vercel适配器 #

Remix针对Vercel有专属适配方案，不要用通用路由规则替代，先完成以下步骤：

• 安装适配器依赖：

  npm install @remix-run/vercel @vercel/node
  

• 根据你的Remix版本添加配置：

  // 非Vite版：remix.config.js
  module.exports = {
    serverBuildTarget: "vercel",
    serverModuleFormat: "esm",
    // 保留原有其他配置
  };
  

  // Vite版：vite.config.js
  import { vitePlugin as remix } from "@remix-run/dev";
  import { defineConfig } from "vite";
  
  export default defineConfig({
    plugins: [
      remix({
        serverBuildTarget: "vercel",
      }),
    ],
  });
  

2. 替换为适配Remix的vercel.json #

删除你当前的配置，改用以下规则，确保路由指向Remix服务端入口：

{
  "buildCommand": "remix vite:build", // 非Vite版替换为"remix build"
  "devCommand": "remix vite:dev", // 非Vite版替换为"remix dev"
  "routes": [
    {
      "src": "/(.*)",
      "dest": "/server/index.js" // 非Vite版可能为"/build/server/index.js"，需匹配实际构建路径
    }
  ]
}

3. 修复React Hydration错误（#418/#423） #

这类错误源于服务端与客户端渲染内容不一致，常见修复方式：

• 禁止在组件顶层直接访问window/document等浏览器对象，改用useEffect延迟执行：

  import { useEffect } from "react";
  
  export default function TargetRoute() {
    useEffect(() => {
      // 此处编写依赖浏览器环境的代码
      if (window) {
        // 例如初始化第三方脚本、读取本地存储等
      }
    }, []);
  
    return <div>路由内容</div>;
  }
  

• 检查路由组件的动态渲染逻辑，确保服务端loader返回的数据与客户端完全一致，避免渲染结果出现差异。

4. 排查部署日志 #

在Vercel控制台查看部署构建日志，确认：

• 依赖安装无报错
• Remix服务端构建成功生成目标文件
• 无编译或配置类错误

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