Remix 1.x在Debian 12编译运行时无法解析含$的动态路径

问题概述 #

• 运行环境：Debian 12 (amd64)，Remix 1.19.3 + TypeScript；相同代码在Mac OS M1环境可正常构建运行
• 构建阶段问题：执行npm run build时，无法解析包含$的动态路径（如~/app/routes/events/$eventID/...），将路径中的枚举文件移至无$的目录后构建成功
• 运行阶段问题：构建成功启动应用后，访问静态路由localhost:3000/events正常，但通过<Link />跳转至含动态段的路由（如/events/afTsd45G）时触发Invariant failed错误

排查与解决步骤 #

1. 修正文件系统大小写不匹配问题 #

Linux文件系统默认大小写敏感，Mac默认不敏感，需确认：

• 动态路由目录/文件的实际命名（如$eventID）与代码中引用的大小写完全一致，避免出现$EventID这类大小写差异
• 代码中路由跳转、数据加载逻辑里的路径参数大小写，与文件系统的目录命名匹配

2. 检查Remix路由配置 #

打开remix.config.js，确认路由相关配置正确：

• 确保appDirectory正确指向app目录，无路径拼写错误
• 若自定义路由映射，确认动态路由规则配置正确，示例：

  module.exports = {
    appDirectory: "app",
    routes(defineRoutes) {
      return defineRoutes((route) => {
        route("/events/$eventID", "routes/events/$eventID.tsx");
      });
    },
    // 其他配置项...
  };
  

3. 验证TypeScript路径别名配置 #

检查tsconfig.json中的路径映射，确保Linux环境下解析正常：

• 确认baseUrl和paths配置正确，示例：

  {
    "compilerOptions": {
      "baseUrl": ".",
      "paths": {
        "~/*": ["./app/*"]
      }
    }
  }
  

• 执行npx tsc --noEmit检查TypeScript编译错误，修复所有路径相关的警告或错误

4. 清理缓存后重新构建 #

Linux环境下缓存可能导致路径解析异常，执行以下命令清理后重新构建：

rm -rf node_modules package-lock.json
npm install
rm -rf build public/build
npm run build
npm start

5. 定位Invariant failed错误根源 #

该错误由Remix内部断言失败触发，可通过以下方式排查：

• 开启开发模式启动应用：NODE_ENV=development npm start，查看控制台完整错误栈，定位触发断言的代码位置
• 检查动态路由组件的loader/action函数，确认是否正确处理params.eventID，避免未处理的undefined参数
• 验证<Link />组件的to属性路径生成正确，示例：

  <Link to={`/events/${event.id}`}>查看事件详情</Link>
  

  避免出现斜杠多写/少写、参数拼接错误等问题

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