在TypeScript项目开发中，模块系统的正确配置直接影响代码的可维护性、兼容性及构建效率。TSConfig提供了一系列精细化模块控制选项，帮助开发者针对不同场景（如库开发、特定环境适配）优化模块解析行为。本节将深入解析--verbatimModuleSyntax、resolvePackageJsonExports/resolvePackageJsonImports及customConditions三个高级配置项的工作原理与实践应用。

1. --verbatimModuleSyntax：严格控制类型导入导出（TypeScript 5.0+）

作为TypeScript 5.0引入的核心特性，--verbatimModuleSyntax旨在简化模块导入处理逻辑，通过强制区分类型导入与值导入，消除传统模式下类型导入可能导致的运行时冗余。其核心机制是：类型相关的导入必须显式使用import type语法，而非类型导入则原样保留，从而确保编译产物中不包含未使用的类型代码。

默认模式与Verbatim模式的编译差异：

• 类型导入：在默认模式下，import { User } from './types'（假设User为类型）可能被编译为const { User } = require('./types')，导致运行时无效代码；而在verbatimModuleSyntax模式下，必须显式写为import type { User } from './types'，编译后该语句会被完全移除。
• 值导入：import { add } from './math'（add为函数）在两种模式下均会保留，但Verbatim模式会严格检查是否存在类型与值的混合导入，例如import { User, add } from './utils'（其中User为类型）会直接报错，需拆分为import type { User } from './utils'和import { add } from './utils'。

注意事项：启用--verbatimModuleSyntax后，所有类型导入必须使用import type，混合导入（同一语句中包含类型与值）将触发编译错误。这一约束虽然增加了前期编码成本，但能显著提升代码可读性和构建效率，尤其适合库项目开发。

2. resolvePackageJsonExports与resolvePackageJsonImports：解析package.json的导出/导入字段

随着ES模块规范的普及，越来越多的npm包通过package.json的exports字段定义多环境入口（如CommonJS/ES模块、浏览器/Node.js环境）。TypeScript通过resolvePackageJsonExports（默认true）和resolvePackageJsonImports（默认true）控制是否解析这些字段，从而正确定位包的实际入口文件。

工作机制示例：
当导入import 'lodash'时，TypeScript会检查lodash包的package.json中exports字段的定义：

{
  "exports": {
    ".": {
      "import": "./esm/lodash.js",
      "require": "./cjs/lodash.js"
    }
  }
}

若resolvePackageJsonExports: true，TS会根据当前项目的模块类型（module或commonjs）自动选择对应入口；若禁用该配置，TS将忽略exports字段，直接查找包根目录下的index.js或index.ts，可能导致模块解析错误。

最佳实践：对于使用现代npm包（如React 18+、Lodash 4.17+）的项目，建议保持默认启用这两个配置，以确保模块解析与包作者的设计意图一致。仅在处理老旧无exports字段的包时，可临时禁用调试。

3. customConditions：自定义package.json导出条件优先级

customConditions配置允许开发者定义自定义导出条件，使TypeScript在解析package.json的exports字段时优先选择特定环境的入口。例如，某些包会为Electron、React Native等特殊环境提供优化实现，通过自定义条件可强制TS选择这些特定版本。

使用示例：
假设某包的package.json定义了自定义条件：

{
  "exports": {
    ".": {
      "node": "./node.js",
      "electron": "./electron.js",
      "default": "./index.js"
    }
  }
}

在TSConfig中配置：

{
  "compilerOptions": {
    "customConditions": [[15](electron)]
  }
}

此时，import 'some-package'会优先选择"./electron.js"入口，而非默认的node或default条件。这一特性在跨环境开发（如同时支持浏览器和Electron）时尤为重要。

案例：库项目的精细化模块配置

某开源工具库需同时支持TypeScript类型导出和Node.js运行时环境，且需适配Electron主进程场景。其TSConfig关键配置如下：

{
  "compilerOptions": {
    "module": "NodeNext",
    "verbatimModuleSyntax": true,  // 确保类型导入/导出严格区分
    "resolvePackageJsonExports": true,  // 解析依赖的exports字段
    "customConditions": [[15](electron)][[16](node)],  // 优先Electron环境入口
    "declaration": true  // 生成类型声明文件
  }
}

• 效果：通过verbatimModuleSyntax确保类型声明文件（.d.ts）中不包含冗余值导入；customConditions保证在Electron环境下使用优化后的模块实现，避免运行时兼容性问题。

实践练习：启用--verbatimModuleSyntax并修复类型导入错误

目标：修改现有TSConfig，启用--verbatimModuleSyntax，并修复因类型导入不规范导致的编译错误。

步骤：

1. 修改TSConfig：在compilerOptions中添加"verbatimModuleSyntax": true。
2. 检查编译错误：运行tsc，定位类似'User' is a type and must be imported using 'import type'的错误。
3. 修复导入语句：
   • 将import { User, add } from './utils'拆分为：
     typescript

     复制代码

     import type { User } from './utils';  // 类型导入
     import { add } from './utils';        // 值导入

   • 将纯类型导入import { Config } from './config'改为import type { Config } from './config'。
4. 验证修复：重新运行tsc，确保无模块相关错误，且编译产物中不含类型导入语句。

通过该练习，可直观理解verbatimModuleSyntax对代码规范性的约束作用，为后续大型项目开发奠定基础。