将外部模块类型声明从.d.ts改.ts是否存在行为差异？

针对你将自定义类型声明从.d.ts改为.ts（内容保留declare module 'x' { ... }）的场景，核心差异与注意事项如下：

1. 类型检查规则差异 #

• .d.ts文件默认被归类为库类型声明文件，当开启skipLibCheck: true时，TypeScript会跳过所有.d.ts的类型校验——这正是你无法捕获自定义声明错误的原因。
• .ts文件属于项目源码文件，不受skipLibCheck配置影响，会被TypeScript完整检查。哪怕文件内容仅为模块声明，也会触发全量类型校验，帮你捕获声明中的语法、逻辑错误，同时无需关闭skipLibCheck来处理node_modules的类型问题。

2. 模块作用域与全局可用性 #

• 若.ts文件无任何顶层import/export语句，其中的declare module 'x'作用与.d.ts完全一致：属于全局模块声明/扩充，所有项目文件都能自动识别这些类型。
• 若.ts文件包含顶层import/export，则文件会被视为一个独立模块，此时内部的declare module 'x'仍会被当作对全局模块'x'的类型补充，但TypeScript会对这类扩充做更严格的校验（比如要求被扩充的模块必须已存在）。

3. 编译输出差异 #

• .d.ts仅提供类型信息，不会被编译为JavaScript文件，也不会出现在输出目录中。
• .ts文件会被编译为JS文件，即使内容只有类型声明，最终也会生成一个空的JS文件。如果不想生成这类无用产物，可通过以下方式处理：
  • 在tsconfig.json的compilerOptions中设置emitDeclarationOnly: true（仅生成.d.ts文件，不生成JS）；
  • 或在tsconfig.json的exclude中排除这些声明文件，但需确保include仍包含它们以保证类型检查生效。

4. 类型合并与优先级 #

• 无论是.d.ts还是.ts中的模块声明，只要针对同一模块'x'，TypeScript都会遵循相同的类型合并规则自动合并。
• 优先级上两者无差异，但.ts的检查更严格：如果声明存在冲突，.ts会直接抛出错误，而.d.ts在skipLibCheck: true时会被忽略。

实操建议 #

将.d.ts改为.ts是解决你当前问题的可行方案，只需注意两点：

• 尽量保持声明文件无顶层import/export，确保类型全局可用；
• 按需配置编译选项，避免生成无用的空JS文件。

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