Remix修改Loader后触发Cannot initialize 'routeModules'错误求助

问题背景 #

原本路由文件中直接导出现有loader函数运行正常：

import { Success } from '@web/components/Success'

export { meta } from '@web/utils/meta'
export { loadPageContent as loader } from '@web/utils/loadContent'

export default Success

修改为调用高阶函数传入指定路径后，页面报错：

Error: Cannot initialize 'routeModules'. This normally occurs when you have server code in your client modules.

修改后的路由代码：

import { Success } from '@web/components/Success'
import { loadPageContentWithPath } from '@web/utils/loadContent'

export { meta } from '@web/utils/meta'
export const loader = loadPageContentWithPath('some-path')

export default Success

对应的loader实现：

export const loadPageContent = async ({ params, request }) => {
  const { pathname } = new URL(request.url)
  // ...其他逻辑
  return fetchContent()
}

export const loadPageContentWithPath = (path) => async ({ params, request }) => {
  const { pathname } = new URL(request.url)
  // ...其他逻辑
  return fetchContent(path)
}

错误原因 #

核心问题是模块加载阶段就执行了服务端相关逻辑：
当你写export const loader = loadPageContentWithPath('some-path')时，路由模块加载时（客户端也会加载该模块）会立即执行loadPageContentWithPath，返回的内部async函数包含服务端特有的逻辑（比如处理request对象、服务端专属的fetchContent实现），导致客户端尝试解析服务端代码，触发错误。

而原来的写法只是导出函数引用，不会在模块加载时执行函数内部逻辑，因此不会触发问题。

解决方案 #

方案1：用包装函数延迟服务端逻辑执行 #

不要在模块顶层调用loadPageContentWithPath，而是导出一个新的async函数，在函数内部调用并传入参数，确保服务端逻辑只在loader运行时（服务端环境）执行：

import { Success } from '@web/components/Success'
import { loadPageContentWithPath } from '@web/utils/loadContent'

export { meta } from '@web/utils/meta'
export const loader = async (args) => {
  return loadPageContentWithPath('some-path')(args)
}

export default Success

方案2：标记路由模块为服务端专属（框架支持时） #

如果使用Remix、Next.js这类框架，可以通过约定将路由模块限定为服务端运行：

• Remix：将路由文件重命名为success.server.jsx（添加.server后缀），框架会仅在服务端加载该模块。
• Next.js App Router：在loader函数内添加'use server'指令，明确标记该函数为服务端函数：

import { Success } from '@web/components/Success'
import { loadPageContentWithPath } from '@web/utils/loadContent'

export { meta } from '@web/utils/meta'
export const loader = async (args) => {
  'use server'
  return loadPageContentWithPath('some-path')(args)
}

export default Success

验证 #

修改后，模块顶层不再执行服务端相关的函数调用，服务端逻辑只会在框架调用loader时（服务端环境）运行，客户端不会接触到服务端代码，错误即可解决。

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