JavaScript / TypeScript / 系统课时
声明无类型模块
声明无类型模块
当 JavaScript 包没有自带类型声明、也找不到对应的 @types 包时,TypeScript 会把导入位置标记为缺少声明。本课用 declare module 先解除阻塞,再把 any 逐步收紧为可检查、可补全的最小类型。
学习目标
- 能定位“找不到模块声明”错误并创建
.d.ts文件 - 能从兜底声明升级为精确的导出类型
- 能识别声明文件未生效和声明过宽的问题
从报错到最小声明
典型报错是 TS7016:运行时模块存在,但编译器找不到类型信息。处理前先检查包内是否已有 .d.ts,再查询是否存在对应的 @types/包名。只有两者都没有时,才需要自己补声明。
在 TypeScript 会扫描到的目录中创建 src/types/legacy-format.d.ts:
declare module "legacy-format";这条声明表示模块存在,但其导出值按 any 处理。它适合临时迁移,却会关闭参数校验、返回值推断和编辑器补全,因此应尽快提高精度。
验证声明是否被加载:
npx tsc --noEmit预期输出:
命令无输出并以退出码 0 结束如果仍然出现 TS7016,检查声明文件是否被 tsconfig.json 的 include、files 或 typeRoots 排除,以及模块名是否与 import 中的字符串逐字一致。skipLibCheck 也不能替代模块声明,它主要跳过声明文件之间的检查。
补成最小可用类型
假设 legacy-format 在运行时通过 CommonJS 导出一个函数,可将声明收紧为项目实际使用到的签名:
declare module "legacy-format" {
function format(input: string): string;
export = format;
}调用端使用与 export = 匹配的导入语法:
import format = require("legacy-format");
const result = format(" hello ");
console.log(result);片段示例依赖项目已安装名为 legacy-format 的 JavaScript 模块,且其行为是去除首尾空白、转为大写并包裹方括号。
预期输出:
[HELLO]此时 format(123) 会在编译阶段报错,返回值会被推断为 string。声明不必一次覆盖库的全部 API,应先描述项目真实使用的成员,再随着调用范围扩大继续补充。
处理导出方式与关键边界
声明必须反映真实导出方式。ES 模块默认导出使用 export default,命名导出使用 export function、export interface 等形式;CommonJS 的单值导出通常使用 export =。
对于图片、样式等非代码资源,可以使用通配模块声明:
declare module "*.svg" {
const url: string;
export default url;
}这类声明描述的是导入结果。若构建工具实际返回组件、原始文本或其他对象,类型也必须同步调整。
声明文件只参与类型检查,不会创建运行时模块。编译通过但执行时报 MODULE_NOT_FOUND,说明依赖安装、路径别名或打包配置仍有问题。也不要长期把整个库声明为 any,更不要凭猜测写出不存在的成员,否则会让编译器产生虚假的安全保证。
本课总结
declare module "包名";能临时解除阻塞,但会把模块降级为any- 精确声明要与真实导出方式一致,并优先覆盖项目实际使用的 API
.d.ts是否被工程包含、模块名是否精确匹配,是声明不生效时的首要检查项
下一课预告
下一课将使用声明合并和模块扩充,为已有类型补充成员,并把全局声明限制在明确的作用域内。