应手动编写 .d.ts 声明文件解决 typescript 无法识别纯 js 第三方库的问题，优先尝试安装 @types 包，若失败则在 types/ 目录下创建模块声明，确保 declare module 结构正确、导出匹配实际用法，并在 tsconfig.json 中配置 include 或 typeroots 使 ts 加载声明。
Vue 项目中用 TypeScript 时，遇到纯 JavaScript 的第三方库（比如没提供 @types、也没内置 types 字段的 npm 包），TypeScript 默认无法识别它的 API，就会报 Cannot find module 'xxx' 或 Could not find a declaration file。解决办法就是手动写一个 .d.ts 声明文件，告诉 TS “这个库长什么样”。整个过程不难，关键是结构要对、位置要准、导出要匹配实际用法。
确认是否真需要自己写声明文件
先别急着动手——很多常用库已有社区维护的类型定义。打开终端运行：
-
npm install -D @types/库名（例如@types/lodash、@types/axios） - 如果安装成功且 TS 不再报错，说明问题已解决，无需自定义
- 若提示
ERR! No matching version found或 VS Code 仍无提示，才进入自定义流程
创建标准的模块声明文件
假设你要为 my-legacy-utils 这个 JS 库补类型，它通过 import utils from 'my-legacy-utils' 使用，且默认导出一个对象。推荐在项目根目录新建 types/my-legacy-utils/index.d.ts（路径清晰、易管理）：
Vue Composition Analyzer
下载
分析 Vue 3 Composition API 使用情况——审计响应式模式、可组合函数设计、ref 与 reactive 的选择、计算属性、watcher 使用及组件……
declare module 'my-legacy-utils' {
const utils: {
formatTime: (ts: number) => string;
deepClone: <t>(obj: T) => T;
throttle: (fn: Function, delay: number) => Function;
};
export default utils;
}</t>
注意几点：
-
declare module是必须的，包裹整个模块声明 - 内容需严格对应 JS 库的实际导出形式（默认导出、命名导出、UMD 全局变量等）
- 不写实现，只描述结构；函数参数和返回值类型尽量具体，避免泛滥用
any
让 TypeScript 正确加载你的声明文件
仅创建文件还不够，TS 编译器得知道去哪找。检查项目根目录的 tsconfig.json：
- 确保
"include"包含了types/**/*，例如："include": ["src/**/*", "types/**/*"] - 如果 types 目录不在根目录，可通过
"typeRoots"显式指定："typeRoots": ["./types", "./node_modules/@types"] - 避免开启
"skipLibCheck": true来掩盖问题——它只是跳过检查，不解决类型缺失
处理特殊场景的常见写法
不同引入方式对应不同声明语法：
-
全局变量（如 script 标签引入的 SDK）：
在types/global.d.ts里写declare const SDK: { init(): void; getVersion(): string }; -
命名导出（如
import { foo } from 'lib'）：declare module 'lib' { export function foo(): void; export const VERSION: string; } -
Vue 插件或组件库（如
import MyComponent from 'xxx/lib/MyComponent.vue'）：
加一条模块声明：declare module 'xxx/lib/MyComponent.vue' { const component: import('vue').DefineComponent; export default component; }
前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
