模块化

约 489 字大约 2 分钟

2026-02-09

在 TypeScript 中，只要一个文件包含顶层 import 或 export，它就会被视为模块。如果一个文件既没有 import，也没有 export，那么它会被当作脚本文件，里面的声明可能会进入全局作用域

显式变为模块

有些文件虽然暂时没有导入导出，但你仍然希望它被当作模块处理，这时可以显式导出一个空对象

export {}

这样做的目的通常是避免全局命名污染

CommonJS 互操作

在 TypeScript 项目里使用 CommonJS 包时，常见写法通常有三种：

import * as fs from 'node:fs'
import { readFileSync } from 'node:fs'
// 在配置允许时：
import fsDefault from 'node:fs'

配置	含义
`esModuleInterop`	允许 CommonJS 模块使用 ES 模块的导入语法
`allowSyntheticDefaultImports`	允许 CommonJS 模块使用默认导入语法

declare 用于告诉 TypeScript 编译器：某个值、函数、模块或命名空间在运行时真实存在，不要尝试去生成它的实现代码，这里只是补充它的类型信息。通常在 .d.ts 文件中进行声明

declare const APP_VERSION: string
declare function formatPrice(input: number): string

如果某个第三方库没有类型定义，可以手动声明它的模块结构

declare module 'legacy-lib' {
  export function format(input: string): string
}

除了 JS/TS 模块，项目里也经常会导入图片、样式等资源，这时也可以通过声明文件告诉 TypeScript 它们的类型

declare module '*.svg' {
  const url: string
  export default url
}

命名空间 namespace 是 TypeScript 早期用于组织代码的一种方式，通常也用于给全局库补充类型。现代项目里，通常优先使用 ESM 模块体系

declare namespace Price {
  function format(n: number): string
}

笔记

新项目一般不建议再用 namespace 作为主要模块组织方式