TypeScript声明文件命名、导入及第三方包声明配置问题咨询

1. 声明文件命名规则与数量规划 #

如果要给每个.ts业务文件对应独立的类型声明文件，不能直接用和业务文件同名的.d.ts（比如stack-player.ts和stack-player.d.ts放在同一目录会被TS视为同一模块，导致导入冲突）。推荐两种实用的命名/组织方式：

• 方式一：给类型文件加专属后缀，比如stack-player.types.ts，直接作为普通TS文件导入（import { Stack } from './stack-player.types'），适合TS项目内部分离类型代码，无需额外配置。
• 方式二：单独创建types/子目录，把声明文件放在里面，比如types/stack-player.d.ts，导入时写import { Stack } from './types/stack-player'。

数量上完全可以按业务文件一对一创建，比如新增mergeObjects.ts，就对应创建mergeObjects.types.ts或者types/mergeObjects.d.ts，保持结构清晰即可。

2. index.d.ts的特殊作用与冲突处理 #

index.d.ts的特殊之处在于：当TS解析某个目录时，会自动把该目录下的index.d.ts作为默认的声明入口。比如你有src/types/index.d.ts，导入整个目录的类型时只需要写import * as MyTypes from './types'，不需要指定具体文件名。

如果当前目录已经有index.ts，绝对不能在同一目录放index.d.ts（会触发模块冲突）。解决办法是把类型的入口声明文件放到子目录，比如src/types/index.d.ts，这样业务代码入口用./index（对应index.ts），类型入口用./types（对应types目录下的index.d.ts），完全隔离不冲突。

3. 无@types的第三方JS包声明文件创建方法 #

步骤如下：

1. 文件名与存放：在项目根目录创建types/文件夹，然后新建[第三方包名].d.ts，比如包名叫xxx-utils，就建types/xxx-utils.d.ts。
2. 配置tsconfig.json：在compilerOptions里添加typeRoots，把自定义的types/目录加入，确保TS能识别：

   {
     "compilerOptions": {
       "typeRoots": ["./node_modules/@types", "./types"]
     }
   }
   

3. 编写声明内容：在.d.ts文件里用declare module 'xxx-utils'包裹类型定义，比如：

   declare module 'xxx-utils' {
     export function formatDate(date: Date): string;
     export type FormatOptions = {
       locale: string;
     };
   }
   

4. 导入使用：和导入普通JS包完全一样，直接import { formatDate } from 'xxx-utils'，TS会自动关联你写的声明文件。

内容的提问来源于stack exchange，提问作者Islam Y-