TypeScript支持多入口点导出/导入类吗？API分层配置疑问

这种将公开API和内部API拆分为不同入口的方案在TypeScript中完全可行，你遇到的TS2307错误是因为缺少了包入口配置和类型声明生成的关键步骤，以下是具体解决方法和最佳实践：

一、核心配置步骤 #

1. 配置package.json的exports字段 #

npm的exports字段是定义包多入口的标准方式，它能明确告诉Node.js、TypeScript和包管理器各个入口对应的文件路径（包括类型声明文件）。在你的package.json中添加如下配置：

{
  "name": "phonenumbers_js",
  "exports": {
    ".": {
      "import": "./dist/index.js",
      "require": "./dist/index.cjs",
      "types": "./dist/index.d.ts"
    },
    "./internal": {
      "import": "./dist/internal.js",
      "require": "./dist/internal.cjs",
      "types": "./dist/internal.d.ts"
    }
  },
  "main": "./dist/index.cjs",
  "module": "./dist/index.js",
  "types": "./dist/index.d.ts",
  "files": ["dist"] // 确保发布npm包时包含编译后的dist目录
}

2. 调整TypeScript编译配置（tsconfig.json） #

要让TypeScript正确生成内部API的类型声明，并支持exports字段的解析，需要修改tsconfig.json的关键配置：

{
  "compilerOptions": {
    "outDir": "./dist", // 指定编译输出目录
    "declaration": true, // 必须开启，自动生成类型声明文件
    "declarationDir": "./dist",
    "module": "ESNext",
    "target": "ES2020",
    "moduleResolution": "NodeNext" // 启用Node.js的模块解析逻辑，支持exports字段
  },
  "include": ["src/index.ts", "src/internal.ts"] // 确保包含内部API的源文件
}

• declaration: true会为internal.ts生成对应的internal.d.ts类型文件，解决TypeScript找不到类型的问题。
• moduleResolution: NodeNext是关键，它让TypeScript能够识别package.json中exports定义的多入口。

3. 验证打包与发布 #

编译项目后，检查dist目录下是否存在：

• index.js、index.d.ts（公开API的编译文件和类型）
• internal.js、internal.d.ts（内部API的编译文件和类型）

发布npm包时，确保files字段包含dist目录，避免遗漏必要文件。

二、最佳实践 #

• 明确标记内部API的风险：在internal.ts的顶部添加注释，明确告知使用者这是内部专用API，不保证向后兼容性：

  /**
   * 内部扩展专用API，仅用于项目内部扩展，不对外提供稳定支持
   * 请勿在业务代码中依赖此模块，后续版本可能会无预警变更或删除
   */
  export class Converter { /* ... */ }
  

• 限制内部API的外部使用：如果你的包是内部团队使用，可以通过CI/CD工具扫描代码，禁止外部业务代码导入phonenumbers_js/internal；如果是公开包，在README中明确说明内部API的非稳定性，引导用户仅使用主入口的公开API。

• 备选方案：命名空间前缀：如果不想使用多入口，也可以在主入口中导出内部API，但加上清晰的前缀（如_internal），不过多入口的方式更能从模块层面区分公开/内部API，边界更清晰。

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