Remix 2.8.1 + Vite导入.server文件触发服务器端模块引用错误

问题原因 #

Remix通过.server文件名后缀标记仅服务器端运行的模块，但Vite的预转换机制会扫描整个路由文件的顶层导入——哪怕你只在action这类服务器专属导出里使用该模块，只要顶层存在.server模块的导入语句，就会被判定为客户端引用，触发报错。

解决方法 #

1. 在action内部动态导入服务器模块 #

不要在路由文件顶层导入，而是在action函数内部动态导入该模块，这样Vite预转换时不会检测到客户端侧的引用：

export async function action({ request }) {
  // 仅在服务器端执行的action内部导入
  const { validateSchema } = await import("../../lib/validation.server");
  
  const formData = await request.formData();
  const validationResult = validateSchema(Object.fromEntries(formData));
  // 后续业务逻辑
}

2. 内联校验逻辑（临时小方案） #

如果校验函数逻辑不复杂，可以直接把validateSchema的代码复制到action函数内，避免跨文件导入的问题，但这种方式不利于代码复用，仅适合简单场景。

3. 配置Vite忽略服务器模块检查（不推荐） #

可以在vite.config.js中添加规则，让Vite跳过对.server后缀文件的客户端检查，但这可能破坏Remix的服务器/客户端隔离机制，需谨慎使用：

import { vitePlugin as remix } from "@remix-run/dev";
import { defineConfig } from "vite";

export default defineConfig({
  plugins: [
    remix({
      serverModuleFormat: "esm",
      ignoredRouteFiles: ["**/*.server.jsx"],
    }),
  ],
});

注意事项 #

Remix的loader、action、headers等导出确实是服务器端专属，但Vite的预转换是针对整个路由文件的，因此必须确保.server模块仅在这些服务器函数内部被导入，不要放在顶层。优先使用动态导入的方案，既保证代码复用，又符合框架运行机制。

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