TypeScript中module与moduleResolution配置的区别及作用

二者对应TypeScript编译流程中完全独立的两个环节，没有强制绑定关系：

• module 控制代码输出规则：决定TS转译后生成的JavaScript采用哪种模块规范，同时校验你写的模块语法是否符合对应规范
• moduleResolution 控制导入解析规则：决定TS在类型检查阶段，按照什么逻辑定位你代码中import/require语句引用的文件和类型声明，不会改动最终输出的JS代码

module 配置的具体影响 #

这个配置直接作用于TS的转译输出环节，影响分为两部分：

1. 语法校验：限制你在代码中可以使用的模块相关语法。比如设为CommonJS时，使用顶级await、import.meta这类ESM专属语法会直接抛出编译错误；设为ES2022时则允许这些语法存在。
2. 输出格式：决定最终生成的JS代码用什么模块语法。举个直观的对比例子，你写的TS源码如下：

   import { readFile } from 'fs'
   export const run = () => readFile('./a.txt')
   

   • 配置为CommonJS时，输出代码会被转换为Node.js传统模块格式：

     "use strict";
     Object.defineProperty(exports, "__esModule", { value: true });
     exports.run = void 0;
     const fs_1 = require("fs");
     exports.run = () => (0, fs_1.readFile)('./a.txt');
     

   • 配置为ESNext时，输出代码会保留原生ESM语法，不做模块格式转换：

     import { readFile } from 'fs';
     export const run = () => readFile('./a.txt');
     

   • 配置为AMD/UMD时，输出代码会包裹对应模块规范的适配代码，适配浏览器端的非原生模块加载场景。

moduleResolution 配置的具体影响 #

这个配置仅在TS的类型检查、路径解析阶段生效，完全不会改动最终输出的JavaScript代码内容。
它的核心作用是告诉TS解析导入路径时的寻址规则：遇到一个导入语句时，要不要补全文件扩展名、按什么顺序查找目录、要不要读取依赖包package.json里的exports/types字段、怎么识别路径别名、怎么区分CJS和ESM包的类型差异。
常见配置的行为差异：

• 设为Classic：TS早期默认的解析规则，不会遍历node_modules查找依赖，不会识别包的exports字段，仅按照文件后缀优先级在相对路径下查找文件，现在基本很少使用。
• 设为Node16/NodeNext：严格对齐Node.js原生的模块解析逻辑，要求相对路径导入必须写全扩展名，会根据包package.json的type字段区分CJS/ESM模块的类型差异，会严格遵循exports字段的导出限制。
• 设为Bundler：对齐Webpack、Vite、Rollup等打包工具的解析逻辑，允许省略导入路径的扩展名、支持导入目录下的index文件、不会强制校验相对路径的扩展名，是目前前端打包项目最常用的配置。

很多开发者遇到的「TS报找不到模块，但代码实际运行正常」的问题，本质就是moduleResolution配置的解析规则和实际运行环境/打包工具的规则不一致导致的，这类问题只会触发类型报错，不会影响最终JS的生成结果。

两个配置独立设计的原因 #

拆分的核心原因是实际开发场景中，「输出的模块格式」和「解析导入的规则」并不是一一绑定的：

• 比如用Vite开发前端项目时，最终需要输出原生ESM格式的代码（对应module: ESNext），但Vite作为打包工具的解析规则和Node原生ESM规则不同，允许省略扩展名、支持路径别名，这时候就需要单独把moduleResolution设为Bundler适配，不需要改动输出的模块格式。
• 比如开发跨Node.js和浏览器的通用库时，可能需要同时输出CJS和ESM两种格式的产物，但类型检查阶段只需要按照Node.js的解析规则校验一次导入逻辑即可，不需要为不同输出格式重复配置解析规则。

如果把两个配置合并，反而无法覆盖这些灵活的工程场景，会导致配置和实际项目需求不匹配。

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