Ubuntu环境下tsconfig配置TS2307找不到模块的问题

已知问题特征 #

• 同类报错仅在Ubuntu系统复现，Windows、macOS环境无异常
• 初步定位问题与tsconfig路径映射配置相关，当前已配置的paths片段如下：

"paths": {
  "@module/kinetic-e2e": ["dist/kinetic-e2e"],
  "@module/kinetic-erp-tester-e2e": ["dist/kinetic-erp-tester-e2e"]
}

• 实际运行时完整报错日志：

[14:02:30] I/launcher - Running 1 instances of WebDriver
[14:02:30] I/direct - Using ChromeDriver directly...
[14:02:36] E/launcher - Error: TSError: ⨯ Unable to compile TypeScript:
projects/metafx/metafx-harness-e2e/src/common/helper.ts(2,29): error TS2307: Cannot find module '@module/kinetic-erp-tester-e2e' or its corresponding type declarations.

需调整的核心配置问题 #

• 缺少baseUrl路径锚定配置
  当前配置仅在paths中声明了产物相对路径，没有设置TS模块解析的基础根路径。Windows环境对无baseUrl的相对路径解析容错更高，但Ubuntu环境下TS路径解析严格遵循规范，缺少baseUrl时，paths的相对路径会被解析到当前编译文件的同级目录，无法匹配项目根目录下的dist产物。需在tsconfig的compilerOptions节点下新增"baseUrl": "."，将所有路径解析的锚点设置为tsconfig所在的项目根目录。
• 路径映射未覆盖类型声明文件
  从TS2307报错描述来看，提示信息同时包含“找不到模块或对应的类型声明”，当前paths配置仅指向产物目录，未匹配对应模块的.d.ts类型声明文件，会降低TS解析的匹配成功率。调整后的参考配置如下：

"compilerOptions": {
  "baseUrl": ".",
  "paths": {
    "@module/kinetic-e2e": ["dist/kinetic-e2e", "dist/kinetic-e2e/index.d.ts"],
    "@module/kinetic-erp-tester-e2e": ["dist/kinetic-erp-tester-e2e", "dist/kinetic-erp-tester-e2e/index.d.ts"]
  }
}

• 校验Ubuntu下目录大小写一致性
  Ubuntu文件系统为严格大小写敏感模式，需确认dist目录下实际生成的模块文件夹名称，与paths中书写的字符串完全匹配。如果构建脚本在Ubuntu环境下输出的目录存在大小写偏差（例如将kinetic-erp-tester-e2e输出为Kinetic-Erp-Tester-E2e），在Windows环境下因大小写不敏感不会触发报错，但在Ubuntu下会直接导致模块定位失败。
• 确认运行时配置的生效优先级
  报错触发源为TSError，说明运行时通过ts-node类的TS加载器做实时编译。这类加载器会按固定优先级读取tsconfig配置，如果项目存在多层tsconfig继承关系，需确认当前修改的paths配置未被上层继承的空paths配置覆盖，确保运行时实际加载的就是调整后的路径映射规则。

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