求助：tsc抛出TS2307错误，无法找到本地安装的模块

我之前也踩过本地包安装+跨平台TypeScript解析的坑，结合你提到的情况——既不是单纯本地文件引用，也不完全是外部私有模块的问题，而且noResolve确实是饮鸩止渴的临时方案，咱们从几个核心方向来解决：

1. 先把本地包的配置拉到位 #

本地包的package.json是TypeScript识别它的关键，跨平台差异很多时候出在这：

• 必须明确main和types（或typings）字段：比如你的本地包编译后入口是dist/index.js，类型定义是dist/index.d.ts，那要写清楚：

  {
    "main": "dist/index.js",
    "types": "dist/index.d.ts"
  }
  

  注意路径统一用正斜杠，别用Windows的反斜杠，TypeScript在不同系统下对路径分隔符的解析逻辑有差异。
• 如果本地包本身是TypeScript项目，确保已经编译生成了.d.ts文件——别指望TypeScript直接去解析本地包的源码（除非你把它加到include里，但这不太规范）。

2. 调整项目的tsconfig.json适配跨平台解析 #

TypeScript的模块解析规则在不同系统下的表现差异，靠配置可以抹平：

• 检查moduleResolution：必须设为node（默认是这个，但有时候会被误改），因为npm本地包遵循Node的模块解析逻辑，这个模式下跨平台的解析行为最一致。
• 用paths映射本地包：如果你的项目用了baseUrl，可以直接在paths里给本地包加个明确的映射，避免路径解析歧义：

  {
    "compilerOptions": {
      "baseUrl": "./",
      "paths": {
        "your-local-pkg-name": ["../path-to-local-pkg/dist"]
      }
    }
  }
  

• 试试preserveSymlinks: true：本地包通过npm install file:../xxx或npm link安装时，本质是软链接，Windows和Unix的软链接解析逻辑不同。开启这个配置后，TypeScript会保留软链接的路径，而不是解析到真实文件路径，能避免很多跨平台的路径不匹配问题。

3. 清理缓存和产物，排除“脏状态”问题 #

跨平台下的依赖缓存经常搞事情：

• 删掉项目和本地包的node_modules，重新执行npm install
• 删掉本地包的编译产物（比如dist文件夹），重新编译本地包
• 清理npm缓存：npm cache clean --force
• 额外注意大小写问题：Windows文件系统大小写不敏感，但macOS/Linux是敏感的。检查你import本地包的路径和实际文件/文件夹的大小写是否完全一致——比如你写import { bar } from 'LocalPkg'，但包名实际是local-pkg，Windows下没问题，但Linux会直接报TS2307。

4. 调整本地包的安装方式 #

不同系统对file:协议的路径解析有差异，可以换个安装方式试试：

• 用npm link：先在本地包目录执行npm link，再在项目目录执行npm link your-local-pkg-name，这种软链接方式的跨平台兼容性相对更好。
• 如果用file:协议，尽量用相对路径+正斜杠，比如"dependencies": { "local-pkg": "file:../local-pkg" }，避免绝对路径（绝对路径在不同系统下格式完全不一样）。

总的来说，这个问题本质是跨平台下TypeScript模块解析的路径规则差异，加上本地包的类型配置或软链接解析的细节问题，从上面几个方向逐一排查，应该能彻底解决，比用noResolve这种破坏正常解析逻辑的临时方案靠谱多了。

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