使用TypeScript部署Heroku时遇模块找不到错误求解决

主要原因 #

• 文件名大小写不兼容：本地开发系统（Windows/macOS）默认不区分文件名大小写，但Heroku基于Linux系统，对文件名大小写严格校验。如果本地引用路径和实际文件名大小写不一致（比如写./camera/playercamera但文件是PlayerCamera.ts），本地能正常解析，但Heroku上会触发模块找不到错误。
• 配置文件模块解析规则缺失：TypeScript的tsconfig.json或Webpack的配置文件未正确配置模块解析逻辑，比如未指定TS文件后缀、baseUrl路径错误，导致Webpack无法定位到TS模块。
• 依赖安装不完整：Heroku默认生产环境下不会安装devDependencies，如果项目的类型声明包（如@types/*）或Webpack相关依赖放在devDependencies中，会导致TS2307类型找不到错误，同时Webpack编译也会因依赖缺失失败。
• 文件路径错误或Git提交遗漏：相对路径书写错误，或者.gitignore误排除了必要的TS源文件，导致Heroku服务器上不存在对应的模块文件。

解决办法 #

1. 统一文件名大小写 #

• 确保所有文件的引用路径和实际文件名完全一致，比如引用./camera/PlayerCamera时，对应文件必须是PlayerCamera.ts。
• 若Git未追踪文件名大小写变更，执行git mv old-name.ts New-Name.ts修改文件名并提交，确保远程仓库的文件名与本地一致。

2. 修正TypeScript和Webpack配置 #

• 调整tsconfig.json：

  {
    "compilerOptions": {
      "baseUrl": "./src", // 根据你的源码根目录调整
      "moduleResolution": "node",
      "resolveJsonModule": true,
      "allowSyntheticDefaultImports": true
    },
    "include": ["src/**/*"], // 确保包含所有TS源文件
    "exclude": ["node_modules", "dist"]
  }
  

• 完善webpack.config.js的resolve规则：

  module.exports = {
    resolve: {
      // 优先解析TS后缀文件
      extensions: ['.ts', '.tsx', '.js', '.jsx'],
      // 指定模块查找目录，避免路径解析错误
      modules: ['src', 'node_modules']
    },
    // 其他Webpack配置...
  };
  

3. 确保依赖完整安装 #

• 如果类型声明包或Webpack依赖在devDependencies中，可通过以下方式处理：
  • 将必要的依赖（如typescript、webpack、@types/*）移至dependencies。
  • 修改package.json的postinstall命令，先安装devDependencies再执行编译：

    {
      "scripts": {
        "postinstall": "npm install --only=dev && webpack --mode production"
      }
    }
    

  • 或在Heroku控制台设置环境变量NPM_CONFIG_PRODUCTION=false，强制安装所有依赖。

4. 验证路径与Git提交 #

• 检查相对路径是否正确，比如当前文件在src/game/目录下，引用../camera/PlayerCamera才是正确的相对路径。
• 打开.gitignore文件，确认未排除src/或其他包含TS源文件的目录。
• 提交代码后，查看远程仓库（如GitHub）是否包含所有需要的TS文件，避免本地存在但远程缺失的情况。

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