理解TypeScript模块-声明-配置

news2025/11/6 23:47:51

模块化

在TypeScript中最主要使用的模块化方案就是ES Module，先理解 TypeScript 认为什么是一个模块：

JavaScript 规范声明任何没有 export 的 JavaScript 文件都应该被认为是一个脚本，而非一个模块
在TypeScript中如果你有一个文件，现在没有任何 import 或者 export，但是你希望它被作为模块处理，添加这行代码 export {}
这会把文件改成一个没有导出任何内容的模块，这个语法可以生效，无论你的模块目标是什么

内置类型导入

需要使用 type 前缀，表明被导入的是一个类型，可以让一个非 TypeScript 编译器比如 Babel、swc 或者 esbuild 知道什么样的导入可以被安全移除
在这里插入图片描述

// ./type/index
export type IDType = number
export interface IFoo {
  name: string
  age: number
}


// main.ts
// import { type IFoo, type IDType } from "./type/index"; // 方式一
import type { IFoo, IDType } from "./type/index"; // 方式二

const id: IDType = 12121212121
const foo: IFoo = {
  name: 'foo',
  age: 18
}

命名空间

TypeScript 有它自己的模块格式名为 namespaces ，它在 ES 模块标准之前出现
在这里插入图片描述

命名空间在TypeScript早期时，称之为内部模块，目的是将一个模块内部再进行作用域的划分，防止一些命名冲突的问题
虽然命名空间没有被废弃，但是由于 ES 模块已经拥有了命名空间的大部分特性，因此更推荐使用 ES 模块，这样才能与 JavaScript 的（发展）方向保持一致
namespace：关键字，用于声明一个命名空间
export：将变量、函数或类导出到命名空间外，以便外部可以访问它们

// 基本语法
namespace MyNamespace {
  export const name: string = 'TypeScript';
  export function greet() {
    console.log('Hello from', name);
  }
  export class Person {
    constructor(public name: string) {}
  }
}

// 使用命名空间
MyNamespace.greet(); // 输出: Hello from TypeScript
const person = new MyNamespace.Person('Alice');
console.log(person.name); // 输出: Alice

// 嵌套语法
namespace MyNamespace {
  export namespace Utils {
    export function logMessage(message: string) {
      console.log('Log:', message);
    }
  }
}
MyNamespace.Utils.logMessage('This is a message'); // 输出: Log: This is a message

// 嵌套语法别名使用
import Utils = MyNamespace.Utils;
Utils.logMessage('Using alias'); // 输出: Log: Using alias

类型查找

之前我们所有的typescript中的类型，几乎都是我们自己编写的，但是也有用到一些其他的类型，我们看下 typescript对类型的管理和查找规则：

一种 .d.ts 文件，它是用来做类型的声明(declare)，称之为类型声明（Type Declaration）或者类型定义（Type Definition）文件
它仅仅用来做类型检测，告知typescript我们有哪些类型
typescript会查找这些类型声明：
- 内置类型声明
- 外部定义类型声明
- 自己定义类型声明

内置类型

内置类型声明是typescript自带的、帮助我们内置了JavaScript运行时的一些标准化API的声明文件

包括比如 Function、String、Math、Date 等内置类型
包括运行环境中的DOM API，比如Window、Document等
TypeScript 使用模式命名这些声明文件lib.[something].d.ts
内置类型声明通常在我们安装typescript的环境中会带有的：https://github.com/microsoft/TypeScript/tree/main/lib
可以通过target和lib来决定哪些内置类型声明是可以使用的，例如startsWith字符串方法只能从称为ECMAScript 6的 JavaScript 版本开始使用
可以通过target的编译选项来配置：TypeScript通过lib根据您的target设置更改默认包含的文件来帮助解决此问题 https://www.typescriptlang.org/tsconfig#lib

外部定义声明

外部类型声明通常是我们使用一些库（比如第三方库）时，需要的一些类型声明

这些库通常有两种类型声明方式：

方式一：在自己库中进行类型声明（编写.d.ts文件），比如axios
- 方式二：通过社区的一个公有库DefinitelyTyped存放类型声明文件
- 该库的GitHub地址：https://github.com/DefinitelyTyped/DefinitelyTyped/
- 该库查找声明安装方式的地址：https://www.typescriptlang.org/dt/search?search=
- 比如安装react的类型声明： npm i @types/react --save-dev

第三方库

什么情况下需要自己来定义声明文件呢？

情况一：使用的第三方库是一个纯的JavaScript库，没有对应的声明文件，比如lodash
情况二：给自己的代码中声明一些类型，方便在其他地方直接进行使用

自定义声明

也可以声明模块，比如lodash模块默认不能使用的情况，可以自己来声明这个模块

declare声明模块：
declare module '模块名' {}，在声明模块的内部，可以通过 export 导出对应库的类、函数等

// XXX.d.ts
declare module 'lodash' {
  export function join(args: any[]): any
}

// XXX.ts
import type { IFoo, IDType } from "./type/index";
import axios from 'axios'
import lodash from 'lodash'
lodash.join(['11', '22'])

const id: IDType = 12121212121
const foo: IFoo = {
  name: 'foo',
  age: 18
}

declare声明文件：

比如在开发vue的过程中，默认是不识别.vue文件的，那么就需要对其进行文件的声明
比如在开发中使用了 jpg 这类图片文件，默认typescript也是不支持的，也需要对其进行声明

// XXX.d.ts
declare module 'lodash' {
  export function join(args: any[]): any
}

declare module '*.vue' {
  import { DefineComponent } from 'vue'
  const component: DefineComponent
  export default component
}

declare module '*.jpg' {
  const src: string
  export default src
}

declare命名空间：
比如在index.html中直接引入了jQuery：https://cdn.bootcdn.net/ajax/libs/jquery/3.6.0/jquery.js 可以进行命名空间的声明
在这里插入图片描述

// XXX.d.ts
declare module 'lodash' {
  export function join(args: any[]): any
}

declare module '*.vue' {
  import { DefineComponent } from 'vue'
  const component: DefineComponent
  export default component
}

declare module '*.jpg' {
  const src: string
  export default src
}

declare namespace $ {
  function ajax(setting: any): void
}

`tsconfig.json`文件

当目录中出现了 tsconfig.json 文件，则说明该目录是 TypeScript 项目的根目录，tsconfig.json文件指定了编译项目所需的根目录下的文件以及编译选项

tsconfig.json文件有两个作用：

作用一：让TypeScript Compiler在编译的时候，知道如何去编译TypeScript代码和进行类型检测
作用二：让编辑器（比如VSCode）可以按照正确的方式识别TypeScript代码，对于哪些语法进行提示、类型错误检测等等

tsconfig.json在编译时如何被使用呢?

在调用 tsc 命令并且没有其它输入文件参数时，编译器将由当前目录开始向父级目录寻找包含 tsconfig 文件的目录
调用 tsc 命令并且没有其他输入文件参数，可以使用 --project （或者只是 -p）的命令行选项来指定包含了 tsconfig.json 的目录
当命令行中指定了输入文件参数，tsconfig.json 文件会被忽略