TypeScript无法找到自定义.d.ts定义文件问题求助

你遇到的核心问题是：为第三方库手写了.d.ts声明文件，但TypeScript始终找不到它，报错提示Could not find a declaration file for module...。你给出的第一次尝试代码如下：

declare class MessageFormat { constructor(message: string); compile: (messageSource: string) => Msg; } export type Msg = (params: {}) => string; export default MessageFormat;

下面咱们一步步排查可能的原因，给出对应的修复方案：

1. 确认声明文件的命名与位置是否合规 #

TypeScript查找声明文件有固定规则，得先确保文件放对地方、名字正确：

• 如果第三方库是通过npm安装的，建议把声明文件放在项目根目录的@types/[库名]/index.d.ts路径下，比如@types/messageformat/index.d.ts，这是TypeScript默认优先查找的位置
• 如果不想放在@types目录下，比如放在项目的src/types/文件夹里，要保证文件名和你导入的模块名一致，比如你用import MessageFormat from 'messageformat'，那声明文件就得叫messageformat.d.ts

2. 配置tsconfig.json让TypeScript识别声明文件路径 #

TypeScript默认不会自动扫描所有目录的.d.ts文件，你需要在tsconfig.json里明确告知它要查找的范围：

• 在include数组中添加声明文件所在的目录，示例配置：

  {
    "compilerOptions": {
      // 你的其他编译配置
    },
    "include": [
      "src/**/*",
      "src/types/**/*.d.ts" // 这里加入你的声明文件目录
    ]
  }
  

• 如果是全局模块的声明，可以设置typeRoots数组，指定TypeScript优先查找的类型文件目录：

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

3. 修正声明文件的写法规范 #

你当前的声明文件写法可以优化，更贴合TypeScript的模块声明规范，避免识别错误：
建议用declare module包裹整个声明，明确指定对应模块名，这样TypeScript能精准关联到目标第三方库：

declare module 'messageformat' {
  export type Msg = (params: Record<string, unknown>) => string;

  export default class MessageFormat {
    constructor(message: string);
    compile(messageSource: string): Msg;
  }
}

4. 排查是否存在声明冲突 #

如果你的项目里已经安装了同名的@types/[库名]包（哪怕是不完整的），可能会和你手写的声明文件产生冲突。可以先检查node_modules/@types目录，若有同名包，要么删除它，要么调整声明文件的优先级。

按照上面的步骤逐一排查调整，应该就能解决TypeScript找不到声明文件的问题了。

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