企业官网建设流程全解析

• 文档
• 教程

在开源项目 The Concise TypeScript Book 的第 58 章 namespacing.md 中，作者将命名空间（Namespace）定位为 TypeScript 中将代码组织进逻辑容器、防止命名冲突、并按相关性分组代码的核心手段，并指出export关键字决定了命名空间能否被模块外部访问。本篇以该章节为主体，完整继承其定义与示例代码，并结合书籍仓库中的相关章节（声明合并、模块类型推断、三斜杠指令等），系统讲解命名空间的声明、使用、跨模块访问以及与 ES 模块体系的协作方式。

命名空间是什么：逻辑容器与命名冲突预防

书籍原文档给出的定义是：

Dalam TypeScript, namespace digunakan untuk mengatur kode ke dalam wadah logis, mencegah benturan penamaan, dan menyediakan cara untuk mengelompokkan kode yang saling berkaitan.（在 TypeScript 中，命名空间用于将代码组织到逻辑容器中，防止命名冲突，并提供一种将相关代码分组在一起的方法。）

也就是说，命名空间承担三重职责：

1. 组织代码：把接口、类型、类、函数等成员收纳进一个具名的“作用域盒子”，让文件结构从平铺变为分层；
2. 防止命名冲突：不同模块中同名的Config、Utils等标识符，被封装进各自的命名空间后互不干扰，访问时通过限定名区分；
3. 分组相关代码：按功能域把相互关联的声明聚拢在一起，形成天然的代码边界。

从源码结构看，本书将命名空间安排在“Erased Structural Types（可擦除的结构化类型）”之后、“Symbols（符号）”之前的位置（参见 目录文件 中Namespacing条目），这与语言特性本身有关：命名空间中的声明会像函数、类一样在编译后生成真实的运行时 JavaScript 对象，而不是仅存在于类型层的可擦除构造。

声明命名空间与内部成员

原文档的核心示例完整展示了命名空间的声明与使用方式：

export namespace MyNamespace { export interface MyInterface1 { prop1: boolean; } export interface MyInterface2 { prop2: string; } } const a: MyNamespace.MyInterface1 = { prop1: true, };

对这个示例可以拆解出三个要点：

命名空间体内的成员需要用 export 显式导出

MyNamespace体内定义了MyInterface1和MyInterface2两个接口，二者都带有export关键字。只有被export的成员才能通过MyNamespace.MyInterface1这样的限定名从命名空间外部访问；未导出的成员只在该命名空间内部可见。这与 ES 模块中“默认不导出、显式导出”的可见性模型一致。

使用命名空间成员需要限定名（qualified name）

示例最后一行const a: MyNamespace.MyInterface1 = { prop1: true };展示了消费方式：通过命名空间名.成员名的形式引用内部成员。这种写法直接解决了“多个模块都定义了一个叫User的接口”这类命名冲突问题——消费方始终知道自己在引用哪个命名空间里的User。

成员既可以是类型也可以是值

示例中展示的是接口（interface）。实际上命名空间体内同样可以放置类、函数、const变量等值声明。当命名空间包含值声明时，编译产物会生成一个真实的 JavaScript 对象，MyNamespace这个标识符在运行时也有对应的实体——这是理解命名空间与纯类型构造（如interface、type）区别的关键。

export 关键字：命名空间能否被模块外部访问

原文档明确指出：

The use of theexportkeyword allows access to the namespace from outside modules.（使用export关键字允许在“外部”模块中访问命名空间。）

这里体现的是 TypeScript 中“全局声明”与“模块作用域”的边界规则：

• 命名空间写在非模块文件（没有顶层import/export的脚本文件）中时，它是全局可见的，任何文件都可以直接引用MyNamespace.MyInterface1；
• 命名空间所在的文件一旦被视为模块（文件中出现了任何顶层import或export），其内部的命名空间就不再自动全局可见。此时，正如原文档强调的，必须通过export namespace MyNamespace { ... }把命名空间本身作为模块成员导出，其他模块才能通过import获取它。

这一点与本书另一章节 type-from-module.md 讲到的机制互为印证：模块导出的值携带其类型信息，导入方可以自动推断。命名空间导出后同样如此——import { MyNamespace } from './my-namespace'之后，导入方既能使用MyNamespace.SomeType作为类型限定名，也能在运行时访问其中导出的类与函数。

与声明合并的协作：跨文件扩展命名空间

命名空间是 TypeScript 中少数天然支持“声明合并”（declaration merging）的构造之一：多个同名namespace块会被编译器合并为一个。本书在 merging-and-extension.md 一章中专门讲解了合并与扩展两种概念，其中“将多个同名声明合并为单一定义”正是命名空间跨文件扩展的基础：

// core.ts export namespace MyNamespace { export interface Base { id: number; } } // extension.ts —— 同名命名空间在另一文件中被合并扩展 export namespace MyNamespace { export interface Base { name: string; } } // 合并后 MyNamespace.Base 同时拥有 id 与 name 两个属性

这种能力使得大型项目可以按模块拆分命名空间成员：核心成员放在主文件，插件或扩展文件以同名namespace追加成员，最终在类型层面聚合为一个整体。需要注意的是，合并的是声明（类型与值各按规则合并），而不是简单的文本拼接；成员冲突仍会报错，这与书籍“Merging and Extension”章节所描述的接口合并行为遵循同一套编译器规则。

命名空间在三斜杠指令体系下的引用

当命名空间（尤其是其声明文件）需要通过传统脚本方式引入而非 ES 模块导入时，可以借助本书 triple-slash-directives.md 章节介绍的三斜杠指令：

/// <reference path="path/to/declaration/file.d.ts" />

指令以三个连续的/开头、置于文件顶部，用于告诉编译器把外部声明文件纳入当前编译单元。对于以全局脚本形式提供命名空间的.d.ts声明文件，/// <reference path="..." />正是将其中的命名空间暴露给当前项目的标准手段。这类指令只影响编译期处理，对运行时行为没有任何影响——这一点与命名空间的运行时产物形成清晰分工：指令负责“让编译器看见”，编译产物负责“让运行时可用”。

本书仓库中的组织方式：从章节结构看命名空间在课程体系中的位置

从仓库结构可以印证本书对该知识点的定位：

• 章节文件位于 website/src/content/docs/book/namespacing.md，front matter 中sidebar.order: 58、label: 58. Namespacing，表明它是全书 60 个编号章节中的第 58 章，紧邻第 60 章 triple-slash-directives.md 之前；
• 多语言站点在 website/src/content/docs/id-id/book/namespacing.md 等处维护了各语言版本的同章节内容，各版本目录均包含 table-of-contents.md 同款的目录导航；
• 书籍配套构建工具链位于 tools/ 目录，如 verify_codeblocks.py 用于校验全书 Markdown 中代码围栏的开闭配对，保证包括本章示例在内的所有代码块在发布前经过格式检查。

小结

回到原文档给出的两个核心事实：命名空间是组织代码的逻辑容器，export决定其模块外可见性。在此基础上，可以提炼出实际使用时的三条实践准则：

1. 用限定名访问成员：MyNamespace.MyInterface1形式是消费命名空间成员的标准方式，也是规避命名冲突的直接手段；
2. 成员与命名空间双重 export：命名空间内部的成员需要export才能被限定名访问；命名空间本身若位于模块文件中，也需要export才能跨模块使用；
3. 善用合并、配合指令：跨文件扩展用同名命名空间合并；传统脚本项目引入全局命名空间声明用/// <reference path="..." />，模块项目则走常规import。

本章内容对应书籍第 58 章，与“合并与扩展”“模块类型推断”“三斜杠指令”等章节共同构成 TypeScript 顶层组织机制的完整知识链。

• 文档
• 教程