如何仅对指定文件应用特定compilerOptions（tsconfig.json）

TypeScript 原生不支持直接为单个文件指定独立的compilerOptions，但有两种成熟方案可以实现「仅指定组件文件开启resolveJsonModule和esModuleInterop」的需求，不需要全局开启这两个配置。

方案1：多tsconfig + 项目引用（官方推荐，无兼容问题） #

这是TypeScript官方提供的标准能力，配置逻辑清晰，不存在兼容隐患，适合需要严格管控配置生效范围的场景：

1. 调整根目录默认tsconfig.json，将不需要全局生效的两个选项置为false，保留原有其他配置：

   {
     "compilerOptions": {
       "keyofStringsOnly": false,
       "resolveJsonModule": false,
       "esModuleInterop": false
     }
   }
   

2. 新建专属配置文件（例如命名为tsconfig.component.json），继承根配置后单独开启目标选项，通过include严格限定配置生效的文件路径，注意必须开启composite: true才能被项目引用识别：

   {
     "extends": "./tsconfig.json",
     "compilerOptions": {
       "resolveJsonModule": true,
       "esModuleInterop": true,
       "composite": true
     },
     "include": ["src/components/your-target-file.tsx"]
   }
   

3. 在根tsconfig.json中添加references字段，指向刚创建的专属配置：

   {
     "compilerOptions": {
       "keyofStringsOnly": false,
       "resolveJsonModule": false,
       "esModuleInterop": false
     },
     "references": [
       { "path": "./tsconfig.component.json" }
     ]
   }
   

配置完成后，TypeScript会自动对include指定的文件应用专属编译配置，其余文件仍然遵循根配置规则。

方案2：轻量适配（适合仅1-2个文件有特殊需求的场景） #

如果需要特殊配置的文件数量极少，没必要拆分多份tsconfig，直接通过代码写法绕过全局配置限制即可：

• 满足resolveJsonModule需求：在需要导入JSON的文件顶部添加模块声明，即可正常导入JSON文件，不需要修改全局配置：

  declare module '*.json' {
    const value: Record<string, unknown>;
    export default value;
  }
  
  // 声明后可正常写导入逻辑
  import componentConfig from './config.json';
  

• 满足esModuleInterop需求：不需要全局开启配置，将CommonJS模块的默认导入写法改为命名空间导入即可，效果和开启esModuleInterop后的默认导入完全一致：

  // 开启esModuleInterop时的写法
  // import React from 'react';
  // 不开全局配置时的等价写法
  import * as React from 'react';
  

注意事项 #

TypeScript默认的配置加载逻辑是：从当前文件所在目录开始向上查找最近的tsconfig文件，加载后对当前目录及子目录生效，不存在原生的单文件级编译选项覆写能力。不要使用依赖TypeScript内部API的第三方hack工具实现单文件配置，这类工具在TypeScript版本升级后极易失效，也会大幅提升项目配置的理解和维护成本。

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