TypeScript项目中tsconfig.jsonc文件引用问题的技术解析

背景介绍

在TypeScript 5.6.3版本中，开发者发现当使用tsc --build命令或tsconfig的references字段引用以.jsonc结尾的配置文件时，TypeScript编译器会错误地将这些文件路径视为目录路径。这个问题影响了项目引用配置的灵活性，特别是对于那些使用JSON with Comments(JSONC)格式来增强配置文件可读性的项目。

问题现象

当开发者在tsconfig.json中使用如下配置时：

{
  "references": [
    { "path": "./tsconfig.dev.jsonc" }
  ]
}

或者直接运行：

tsc --build ./tsconfig.dev.jsonc

TypeScript编译器会错误地尝试访问tsconfig.dev.jsonc/tsconfig.json文件，而不是直接加载指定的.jsonc文件。这与TypeScript文档中明确说明的行为不符，文档指出引用路径可以指向包含tsconfig.json的目录，也可以直接指向配置文件本身（无论文件名是什么）。

技术分析

深入分析TypeScript源码后发现，问题的根源在于resolveConfigFileProjectName函数的实现逻辑。该函数会无条件地为不以.json结尾的路径追加tsconfig.json，而没有考虑.jsonc扩展名的情况。

相比之下，tsc --project命令和tsconfig的extends字段能够正确处理.jsonc文件，因为它们会先检查路径是否指向现有目录，只有在确认是目录时才追加tsconfig.json。

解决方案建议

针对这个问题，最合理的解决方案是修改resolveConfigFileProjectName函数的逻辑，使其行为与tsc --project保持一致：

1. 首先检查给定路径是否指向现有目录
2. 如果是目录，则追加tsconfig.json
3. 如果不是目录，则直接使用原路径

这种方案的优势在于：

• 不需要修改现有的Extension枚举类型，避免潜在的兼容性问题
• 与TypeScript其他部分的行为保持一致
• 实现简单且风险可控

对开发者的影响

这个问题会影响以下开发场景：

1. 使用JSONC格式增强配置文件可读性的项目
2. 需要引用特定名称配置文件的复杂项目结构
3. 自动化构建系统中需要灵活指定配置文件的场景

开发者暂时可以通过以下方式规避此问题：

• 使用.json替代.jsonc扩展名
• 通过目录引用而非直接文件引用
• 等待官方修复后升级TypeScript版本

总结

TypeScript编译器对.jsonc配置文件引用的处理不一致问题，反映了构建系统在路径解析逻辑上的一个小缺陷。通过使tsc --build和references的行为与其他命令保持一致，可以提升TypeScript配置系统的整体一致性和灵活性。这个问题虽然不会影响大多数标准配置的项目，但对于那些需要更复杂配置结构的项目来说，修复后将提供更好的开发体验。