为何设置"moduleResolution": "node"可解决TS7016声明文件查找错误？及声明文件存放位置的选型疑问

我来帮你拆解这两个问题，先搞清楚为什么改moduleResolution能解决错误，再聊聊声明文件存放的选型~

一、为什么设置moduleResolution: "node"能解决TS7016错误？ #

首先得说清楚你用的@tsconfig/node18配置的默认行为：它默认启用的是moduleResolution: "node16"模式，这种模式是TypeScript为适配Node.js的ES模块（ESM）和CommonJS（CJS）混合场景设计的，解析规则比传统的node模式严格很多。

具体到你的场景：

• 在node16模式下，TypeScript会严格遵循Node.js的ESM解析逻辑：先看包的package.json里的exports字段，如果没有才会 fallback 到main和types字段。而且对于types字段的路径，它会默认认为类型文件应该和JS文件在同一层级，或者通过exports明确指定位置——你的ModuleA把类型文件放在了./dist/types/子目录，types字段指向这个路径，但node16模式下的解析器没办法正确关联这个嵌套路径和模块入口，所以就抛出了TS7016（找不到类型定义）的错误。
• 改成moduleResolution: "node"（也就是传统的Node.js CJS解析模式）后，解析逻辑回到了更宽松的规则：它会直接读取package.json里types字段指定的路径，不管这个路径和main的路径是否在同一层级，只要路径正确就能找到对应的类型文件，错误自然就解决了。

二、声明文件放在/dist/types/子目录还是/dist根目录？ #

这两种方式各有优劣，我们结合实际场景来分析：

1. 放在/dist根目录（你的Option2做法） #

• 优势：
  • 兼容性拉满：不管是node还是node16/nodenext解析模式，都能直接识别，完全符合TypeScript官方的推荐方案，能避免很多解析层面的坑。
  • 配置简单：不需要额外设置declarationDir到子目录，TS编译后自动把.d.ts和.js文件放在同一目录，结构直观，新手友好。
• 劣势：
  • 目录文件稍显杂乱：当你的包比较大时，编译后的.js、.d.ts、.map文件会混在一起，可能会增加文件查找的成本，但其实很多成熟的TS包（比如npm上的常用工具库）都采用这种方式，实际使用中影响不大。

2. 放在/dist/types/子目录 #

• 优势：
  • 目录结构更清晰：类型文件和编译后的JS文件、sourcemap等分离，便于管理，尤其是当你需要单独处理类型文件（比如单独打包类型、发布独立的类型包）时，这个结构会更方便。
• 劣势：
  • 兼容性需要额外配置：如果你的项目要支持node16/nodenext解析模式，仅靠types字段是不够的——你需要在ModuleA的package.json里配置exports字段，明确指定类型入口，比如：

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

    这样node16模式下的解析器就能正确找到类型文件，而不需要修改ModuleB的解析模式。如果不配置exports，就只能像你那样修改ModuleB的moduleResolution为node，这会限制ModuleB的解析模式选择。

选型建议 #

• 如果你的包是纯CommonJS，且不需要考虑ES模块的严格解析场景，两种方式都可以，但更推荐放在/dist根目录，减少配置成本和踩坑概率。
• 如果你的包需要支持ES模块（比如同时提供ESM和CJS版本），或者你非常在意目录结构的整洁性，那可以选择放在/dist/types/子目录，但一定要配置package.json的exports字段来明确类型入口，确保不同解析模式下都能正常找到类型文件。

内容来源于stack exchange