发布含.d.ts声明文件的库时TypeScript模块查找错误求助

问题核心 #

你的package.json exports配置不符合Node.js/TypeScript的子路径导出规范，导致TS无法识别the-library/foo这个导入路径对应的模块和类型文件。

修复步骤 #

1. 修正package.json的exports结构
   子路径导出的key必须以./开头，否则TS和Node.js无法将其识别为合法的子路径。同时补充import条件适配ES模块场景：

{
  "name": "the-library",
  "type": "module",
  "files": ["./lib/**/*"],
  "exports": {
    "./foo": {
      "import": "./lib/foo.js",
      "default": "./lib/foo.js",
      "types": "./lib/foo.d.ts"
    }
  }
}

2. 更新消费项目的tsconfig.json
   TypeScript只有在moduleResolution设为node16或nodenext时，才会正确解析package.json exports中的类型映射。修改消费项目的tsconfig：

{
  "compilerOptions": {
    "moduleResolution": "node16",
    "module": "ESNext",
    "target": "ESNext"
    // 其他配置...
  }
}

3. 验证文件可用性

• 确认本地link或安装后的库目录中，lib/foo.d.ts确实存在（检查package.json的files字段是否正确包含了所有类型文件）
• 如果是本地开发用npm link，重新执行npm link确保文件同步

4. 强制刷新TS缓存
   在VS Code中执行：

• 按Cmd+Shift+P打开命令面板
• 选择「TypeScript: Restart TS Server」
• 必要时删除消费项目的node_modules并重新安装依赖

兜底方案（可选） #

如果上述步骤仍未解决，可在库的package.json中添加typesVersions字段作为补充：

{
  "typesVersions": {
    "*": {
      "foo": ["./lib/foo.d.ts"]
    }
  }
}

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