«Could not find a declaration file»：如何让 TypeScript 与任何 JS 模块友好相处

「隐形」错误，每个 TypeScript 开发者都曾遇到

您正在编写 TypeScript 代码，一切顺利，但突然——导入语句下出现红色波浪线。编译器报告了一条令人不安的信息：Could not find a declaration file for module 'module-name'. '/path/to/module-name.js' implicitly has an 'any' type。如果您曾使用过 TypeScript，您很可能遇到过这条消息。当您尝试导入一个没有声明文件（通常扩展名为 .d.ts）的 JavaScript 模块时，就会出现此错误。

在 Stack Overflow 上，这个问题获得了数千次浏览。这并非偶然：问题看似复杂，但实际上有几种简单而优雅的解决方案。在本文中，我们将分析错误产生的原因，并比较四种主要的解决方法。您将了解如何根据具体情况选择合适的方法，并永远告别「隐形」类型。

为什么 TypeScript 需要声明？

TypeScript 是 JavaScript 的超集，增加了静态类型检查。当您编写 import * as _ from 'lodash' 时，TypeScript 需要知道变量 _ 的类型。如果模块没有 .d.ts 文件，编译器无法检查类型，默认会将模块类型赋值为 any。这破坏了类型检查的严格性，因此 TypeScript 会向您发出警告。实际上，这不是运行时错误，而是编译时警告，但在严格模式项目（strict: true）中，它可能会阻止构建。

现在让我们进入解决方案。我们将介绍四种方法，从最简单到最灵活。

解决方案 1：快速而粗糙的方法——declare module

最简单的方法是手动创建一个声明文件。为此，在您的项目中添加一个 global.d.ts（或 types.d.ts）文件，并写入：

// global.d.tsdeclare module 'module-name';

这行代码告诉 TypeScript：「该模块存在，但其类型为 any」。问题解决了，但您失去了类型化的所有优势。这种方法适用于快速原型开发，或者模块仅在一两处使用的情况。但对于生产环境项目，这不是最佳选择。

• 优点： 代码量最少，无需安装包。
• 缺点： any 类型抹杀了 TypeScript 的意义；如果模块更新，您将无法得知 API 的变化。

解决方案 2：使用 @types 包

对于大多数流行的 npm 模块，都有单独的声明包。例如，lodash 对应 @types/lodash。通过 npm 或 yarn 安装它们：

npm install --save-dev @types/lodash

之后，TypeScript 会自动找到声明，错误就会消失。如果您使用 TypeScript 2.0+，它会自动搜索 @types 文件夹。这是标准且推荐的方法。

• 优点： 完整的类型化，社区支持，自动更新。
• 缺点： 并非所有模块都有 @types（例如，小众库）。

如何检查是否有类型？请访问 npm 页面 或运行 npm info @types/模块名。如果找不到包，请转到下一个解决方案。

解决方案 3：启用 allowJs 和 checkJs

如果您编写的项目混合了 TypeScript 和 JavaScript，可以允许编译器检查 JS 文件。为此，在 tsconfig.json 中添加：

{  "compilerOptions": {    "allowJs": true,    "checkJs": false  }}

allowJs 选项允许在 TS 文件中导入 JS 模块。此时 TypeScript 将尝试