TypeScript模块与命名空间详解：区别、规范及合并规则

作者：半夏

时间：2026-10-26

本文深入解析TypeScript中模块与命名空间的核心概念。介绍全局模块的风险及文件模块（外部模块）的隔离特性，对比AMD、SystemJs与ES模块现状，推荐CommonJS规范。阐述命名空间在大型项目中的组织作用，并明确两者在作用域、唯一性及合并行为上的关键差异，帮助开发者避免命名冲突并优化代码结构。

文章目录

一、模块

1. 全局模块

默认情况下，新建的TypeScript文件中的代码会处于全局命名空间内。

由于全局变量空间存在风险，容易与文件内部的代码产生命名冲突，因此官方推荐使用下文介绍的文件模块机制。

示例：

// 由于此时默认为全局变量
// 因此会报错：无法重新声明块范围变量“name”。ts(2451)
let name = '张三';

2. 文件模块

文件模块也常被称为外部模块。当TypeScript文件的根层级包含import或export语句时，该文件将创建一个独立的作用域。

在TypeScript中，模块通常指代外部模块，其核心目的是实现代码复用。

模块在自身的作用域内执行，而非全局作用域。

模块内部的变量、函数或类等成员在外部默认不可见，必须通过导出（export）操作才能被外部访问。

若需使用模块中导出的变量，必须在其他文件中通过导入（import）语句引入。

示例：

// 此时a，b和默认导出的name可以在其他文件导入使用
// c由于未导出，因此在其他文件导入c时会报错
export const a = 1;
export const b = 2;
const c = 3;
export default { name: 'Tom' }
// 导入
// import { a, b } from './xxx.ts'

3. 模块规范

AMD：不建议使用，该规范仅适用于浏览器环境。
SystemJs：虽为良好的实验性方案，但已被ES模块取代。
ES模块：目前尚未完全就绪，浏览器支持仍在逐步完善中。
推荐使用module: commonjs配置，CommonJS规范在Node.js和浏览器环境中均得到支持。

二、命名空间

在代码量较大的项目中，为避免命名空间冲突，可将相似的函数、类或接口封装在命名空间内。

命名空间可将代码包裹起来，仅通过export关键字向外暴露需要在外部访问的对象。

命名空间属于内部模块，主要用于组织代码结构，防止命名冲突。

示例：

// 注意：此处可以在当前文件直接使用，也可以在其他文件导入使用
export namespace person {
  class Woman { };
  // 此处加了export关键字才会被导出，否则则为私有
  export class Man {
    eat() { return '吃饭' }
  }
}
export namespace animal {
  class Bird { };
  // 此处加了export关键字才会被导出，否则则为私有
  export class Tiger {
    eat() { return '吃肉' }
  }
  // 命名空间嵌套命名空间
  export namespace monkeyArea {
    export class Monkey {
      eat() { return '吃水果' }
    }
  }
}
let p = new person.Man();
console.log(p.eat()); // 吃饭
let t = new animal.Tiger();
console.log(t.eat()); // 吃肉
let m = new animal.monkeyArea.Monkey();
console.log(m.eat()); // 吃水果