JavaScript / TypeScript / 系统课时

声明无类型模块

声明无类型模块

当 JavaScript 包没有自带类型声明、也找不到对应的 @types 包时,TypeScript 会把导入位置标记为缺少声明。本课用 declare module 先解除阻塞,再把 any 逐步收紧为可检查、可补全的最小类型。

学习目标

  • 能定位“找不到模块声明”错误并创建 .d.ts 文件
  • 能从兜底声明升级为精确的导出类型
  • 能识别声明文件未生效和声明过宽的问题

从报错到最小声明

典型报错是 TS7016:运行时模块存在,但编译器找不到类型信息。处理前先检查包内是否已有 .d.ts,再查询是否存在对应的 @types/包名。只有两者都没有时,才需要自己补声明。

在 TypeScript 会扫描到的目录中创建 src/types/legacy-format.d.ts:

ts
declare module "legacy-format";

这条声明表示模块存在,但其导出值按 any 处理。它适合临时迁移,却会关闭参数校验、返回值推断和编辑器补全,因此应尽快提高精度。

验证声明是否被加载:

bash
npx tsc --noEmit

预期输出:

text
命令无输出并以退出码 0 结束

如果仍然出现 TS7016,检查声明文件是否被 tsconfig.json 的 include、files 或 typeRoots 排除,以及模块名是否与 import 中的字符串逐字一致。skipLibCheck 也不能替代模块声明,它主要跳过声明文件之间的检查。

补成最小可用类型

假设 legacy-format 在运行时通过 CommonJS 导出一个函数,可将声明收紧为项目实际使用到的签名:

ts
declare module "legacy-format" {
  function format(input: string): string;
  export = format;
}

调用端使用与 export = 匹配的导入语法:

ts
import format = require("legacy-format");

const result = format(" hello ");
console.log(result);

片段示例依赖项目已安装名为 legacy-format 的 JavaScript 模块,且其行为是去除首尾空白、转为大写并包裹方括号。

预期输出:

text
[HELLO]

此时 format(123) 会在编译阶段报错,返回值会被推断为 string。声明不必一次覆盖库的全部 API,应先描述项目真实使用的成员,再随着调用范围扩大继续补充。

处理导出方式与关键边界

声明必须反映真实导出方式。ES 模块默认导出使用 export default,命名导出使用 export function、export interface 等形式;CommonJS 的单值导出通常使用 export =。

对于图片、样式等非代码资源,可以使用通配模块声明:

ts
declare module "*.svg" {
  const url: string;
  export default url;
}

这类声明描述的是导入结果。若构建工具实际返回组件、原始文本或其他对象,类型也必须同步调整。

声明文件只参与类型检查,不会创建运行时模块。编译通过但执行时报 MODULE_NOT_FOUND,说明依赖安装、路径别名或打包配置仍有问题。也不要长期把整个库声明为 any,更不要凭猜测写出不存在的成员,否则会让编译器产生虚假的安全保证。

本课总结

  • declare module "包名"; 能临时解除阻塞,但会把模块降级为 any
  • 精确声明要与真实导出方式一致,并优先覆盖项目实际使用的 API
  • .d.ts 是否被工程包含、模块名是否精确匹配,是声明不生效时的首要检查项

下一课预告

下一课将使用声明合并和模块扩充,为已有类型补充成员,并把全局声明限制在明确的作用域内。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

声明无类型模块

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通