TypeScript 5.7 中 JSON 类型导入与导入属性的兼容性问题解析

在 TypeScript 5.7 版本中，开发者遇到了一个关于 JSON 文件类型导入与导入属性(import attributes)的兼容性问题。这个问题主要出现在当开发者尝试使用 import type 语法导入 JSON 文件时，TypeScript 编译器会要求添加 type: "json" 的导入属性，但同时又禁止在类型导入中使用导入属性，形成了一个两难的局面。

问题背景

在 TypeScript 项目中，开发者经常需要导入 JSON 文件作为类型定义。在 5.3.3 到 5.7.2 版本之间的某个变更中，TypeScript 开始强制要求为 JSON 导入添加类型声明。这原本是为了提高类型安全性，但却与类型导入的语法规则产生了冲突。

具体表现

开发者尝试以下三种方式导入 JSON 文件：

1. 纯类型导入：

import type enMessages from "./en.json";

编译器报错：要求必须添加 type: "json" 导入属性

2. 带导入属性的类型导入：

import type enMessages from "./en.json" with { type: "json" };

编译器报错：禁止在类型导入中使用导入属性

3. 常规导入：

import enMessages from "./en.json" with { type: "json" };

虽然编译器通过，但会导致 ESLint 的 import/no-extraneous-dependencies 规则报错，因为这种导入方式实际上会将 JSON 包含在运行时中，而开发者可能只需要类型信息

技术分析

这个问题的核心在于 TypeScript 对 JSON 模块的类型系统处理与 ECMAScript 模块系统的交互方式。TypeScript 5.7 加强了对 JSON 导入的类型检查，要求明确声明导入的是 JSON 数据，这是为了确保类型安全。然而，类型导入语法(import type)的设计初衷是纯粹用于类型系统，不应该影响运行时行为，因此不允许添加任何会影响实际导入行为的属性。

解决方案

目前推荐的临时解决方案是使用常规导入方式并添加 type: "json" 属性，同时通过 ESLint 配置忽略相关规则的检查。TypeScript 团队已经确认这是一个需要修复的问题，未来的版本可能会允许在类型导入中使用不影响运行时的导入属性，或者自动推断 JSON 导入的类型而不需要显式声明。

最佳实践建议

在问题修复前，开发者可以：

1. 对于仅需要类型的 JSON 导入，使用常规导入方式并添加注释忽略 ESLint 警告
2. 考虑将频繁使用的 JSON 类型提取到单独的 .d.ts 声明文件中
3. 在团队内部统一约定处理方式，保持代码一致性

这个问题反映了类型系统与实际模块系统交互时的复杂性，也提醒我们在升级 TypeScript 版本时需要特别注意类型导入相关的变化。