企业官网建设流程全解析

• 文档
• 教程

命名空间（namespace）是 TypeScript 中一组用于组织代码与类型声明的传统语法，其本质对应 JavaScript 中经典的 IIFE（立即执行函数）加对象合并模式。本文以《TypeScript Deep Dive》中文版 docs/project/namespaces.md 为核心，结合本仓库 docs/project/modules.md、docs/project/declarationspaces.md、docs/tips/outFileCaution.md 等章节，完整讲解命名空间的底层运行原理、嵌套用法，并给出"什么场景该用、什么场景该用模块"的实战判断依据。

命名空间的前身：JavaScript 的 IIFE 分组模式

在 ES 模块（ES Modules）尚未普及的年代，JavaScript 开发者普遍通过"立即执行函数 + 对象合并"来模拟命名空间。TypeScript 的namespace语法正是对这一常见模式的直接描述与升级。

先看经典的 JavaScript 写法：

(function(something) { something.foo = 123; })(something || (something = {}));

这里的核心是something || (something = {})：如果something已经存在，则沿用现有对象；否则先创建一个新对象再传入。它允许匿名函数function (something) {}向现有对象添加内容，或者创建一个新对象，然后向该对象添加内容。这意味着你可以拥有两个由某些边界拆成的块，且彼此共享同一个对象：

(function(something) { something.foo = 123; })(something || (something = {})); console.log(something); // { foo: 123 } (function(something) { something.bar = 456; })(something || (something = {})); console.log(something); // { foo: 123, bar: 456 }

两次 IIFE 分别向同一个something对象追加了foo与bar属性，最终得到{ foo: 123, bar: 456 }。这种模式在 JavaScript 中很常见，其核心价值在于：确保创建的变量不会泄漏至全局命名空间。当基于文件模块使用时，你无须担心全局污染问题，但该模式仍然适用于"一组函数的逻辑分组"这一场景——TypeScript 的namespace关键字正是对这种分组的语言级描述。

TypeScript 的 namespace 关键字

TypeScript 提供了namespace关键字来声明一个命名空间块，块内通过export对外暴露成员，未加export的成员则保持私有：

namespace Utility { export function log(msg) { console.log(msg); } export function error(msg) { console.log(msg); } } // usage Utility.log('Call me'); Utility.error('maybe');

调用方式与访问一个普通对象属性一致，通过Utility.log(...)即可访问命名空间内导出的函数。

编译输出：与手写 IIFE 完全一致

namespace关键字编译后的 JavaScript 代码，与我们早些时候看到的 JavaScript 模式一样。将上述Utility命名空间编译为 ES5 后，输出大致如下：

(function (Utility) { // 添加属性至 Utility })(Utility || Utility = {});

也就是说，TypeScript 编译器在编译阶段自动为你生成了手写 IIFE 时的样板代码，并把命名空间内的所有export成员挂载到传入的Utility对象上。这意味着你可以把"命名空间"理解为一组语法糖：编写时使用更清晰的声明式语法，运行时则退化为对象合并逻辑，与纯 JavaScript 生态完全兼容。

这里可以与声明空间的概念相互印证。在 docs/project/declarationspaces.md 中，TypeScript 存在类型声明空间与变量声明空间两种空间。命名空间通过export同时在这两种空间产出成员：导出的函数、变量进入变量声明空间（可用于运行时调用），而命名空间本身也可以承载并导出类型。当命名空间中导出了一个类Foo时，它既为类型声明空间提供了一个类型Foo，也为变量声明空间提供了一个变量Foo，因此既可以用作类型注解，也可以当作值传递。

命名空间的嵌套

值得注意的一点是，命名空间是支持嵌套的。因此，你可以做一些类似于在Utility命名空间下嵌套一个命名空间Messaging的事情：

namespace Utility { export namespace Messaging { export function log(msg: string) { console.log(msg); } } } // 使用嵌套命名空间 Utility.Messaging.log('hello');

嵌套时内层命名空间也需要export，外层才能从外部访问。嵌套命名空间在编译后依然遵循"对象挂载"的合并逻辑，内层命名空间会以对象属性的形式挂载到外层命名空间对应的对象上。这种能力适合表达"领域 > 子领域"式的分层组织，例如App.Models.User、App.Utils.Format这类带层级语义的命名。

命名空间与全局作用域的关系

需要特别说明：命名空间声明的变量会暴露在它所处的顶层作用域中。若你在一个没有import/export的脚本文件（全局脚本）里声明namespace Utility，那么Utility会出现在全局作用域上——在浏览器中即挂载到window。这一行为与 docs/project/modules.md 中"全局模块"的描述一致：默认情况下，开始在一个新的 TypeScript 文件中写代码时，它处于全局命名空间中。正因如此，docs/tips/outFileCaution.md 明确指出：你可以使用命名空间，但是它仍然在window上，命名空间仅仅是一个临时的解决方式；如果公司有多个独立工作的团队，当有人决定尝试集成两个程序编写 app 时，则很可能存在命名冲突。

编译上下文中与命名空间相关的能力

命名空间在编译层面的行为与tsconfig.json的配置紧密相关。根据 docs/project/compilationContext.md，编译上下文通过tsconfig.json定义：哪些文件是有效的、使用哪些编译选项。

其中与命名空间直接相关的选项包括：

• outFile：将多个命名空间文件合并输出为一个文件。命名空间依赖编译顺序，若多个文件分别声明同一命名空间，编译器需要以正确顺序合并才能保证运行时对象属性的逐步挂载。该选项应谨慎使用（详见下文"为什么项目主体推荐模块"）。
• module：指定模块系统（commonjs、amd、system、umd、es2015等）。文件模块的编译输出依赖该选项；而namespace的输出是独立于模块系统的 IIFE 合并逻辑。
• moduleResolution：模块解析策略，module: commonjs时默认开启node策略。

典型的最小配置如下：

{ "compilerOptions": { "target": "es5", "module": "commonjs", "outFile": "./dist/app.js" } }

命令行运行方式为：直接运行tsc（会在当前目录或父级目录查找tsconfig.json），或使用tsc -p ./path-to-project-directory指定项目目录；tsc -w可启用监听模式，在检测到文件改动后重新编译。

命名空间跨文件合并的典型场景

命名空间最具实用价值的一个场景是跨文件合并同一命名空间，例如在 docs/tips/outFileCaution.md 中展示的拆分写法：

// foo.ts namespace App { export const foo = 123; }

// bar.ts namespace App { export const bar = foo + 456; }

两个文件声明了同一个namespace App，编译时 TypeScript 会将其合并为一个App对象。但这一模式对编译顺序极其敏感：如果bar.ts先于foo.ts被编译，运行时foo尚未挂载，bar就会被赋值为NaN。这正是"命名空间依赖全局执行顺序"这一特性的直接体现，也是后续推荐模块化的重要原因之一。

命名空间与模块：官方建议与取舍

文档的最终结论非常明确：对于大多数项目，我们建议使用外部模块（文件模块）和命名空间，来快速演示和移植旧的 JavaScript 代码。这句话包含两层含义：

1. 模块是主体：项目主体应使用文件模块（外部模块），即在文件根级别使用import/export建立局部作用域，避免全局污染。详见 docs/project/modules.md。
2. 命名空间的定位：命名空间适合"快速演示"和"移植旧的 JavaScript 代码"——将存量 JS 的 IIFE 分组迁移为 TypeScript 时，namespace是近乎一一对应的直译，迁移成本最低；在做技术演示、脚本原型时，命名空间也可以快速组织代码。

为什么项目主体推荐使用模块而非命名空间

docs/tips/outFileCaution.md 从多个维度解释了谨慎使用--outFile（即通过命名空间 + 文件合并构建单文件）的原因，这些原因正是命名空间方案在实际工程中的短板：

• 运行时的错误：类的继承在运行时中断。若foo.ts声明class Foo {}、bar.ts声明class Bar extends Foo {}，但没有按正确顺序编译（例如tsc bar.ts foo.ts），虽然能编译成功，却会在运行时抛出ReferenceError。命名空间的模块拆分同理，顺序错误会把NaN赋给变量。
• 快速编译：--out选项实际上使用了较慢的构建方式，单独的.ts文件不会被编译成单独的.js文件；由于 source map 基于长度编码且对位置信息敏感，大部分 source map 都会在编译时重新构建。
• 全局作用域：命名空间仍然会暴露在window（浏览器环境）上，只是临时解决方式；///<reference也不例外，会引入难以维护的全局上下文。多团队集成时很容易发生命名冲突。
• 难以分析 / 难以扩展 / 代码重用 / 多目标 / 单独编译：文件无法被单独编译——a.ts中namespace M { var s = t; }的输出完全取决于b.ts中t的声明方式（namespace M { export var t = 5; }或var t = 5;），因此a.ts不能脱离上下文单独编译；跨项目重用隐式依赖关系的代码也很困难。

综上，文档给出的建议是：--out做的是一些构建工具的工作，这些构建工具也能受益于外部模块所提供的依赖关系，因此推荐使用外部模块，让构建工具创建单文件的.js。

模块方案速览

模块方案的核心要点（详见 docs/project/modules.md）：

• 文件根级别含有import或export时，该文件即成为模块，创建本地作用域，声明不会"污染"全局命名空间；
• 使用module: commonjs编译选项 + ES 模块语法（export、import）编写模块；
• 相对模块路径（以.开头）按相对路径解析；非相对路径则按 Node 模块解析策略在各级node_modules中查找；
• 可通过declare module 'somePath'（见 docs/typings/ambient.md 的全局声明思路）重写模块的路径查找，用于迁移期快速声明无类型定义的第三方库。

命名空间 + import：跨命名空间移动类型与值

命名空间并非只能通过全限定名调用。在 docs/typings/movingTypes.md 中给出了一个实用技巧：当类型定义在命名空间（或模块）内部时，import是唯一能同时搬运"类型"与"值"的方式：

namespace importing { export class Foo {} } import Bar = importing.Foo; let bar: Bar; // ok

这里import Bar = importing.Foo会同时把Foo的类型与值（类构造器）复制到Bar，因此Bar既可用作类型注解，也可用作变量。相比之下，普通的const Bar = Foo仅仅复制到变量声明空间，let bar: Bar会报cannot find name 'Bar'——这正是"类型声明空间与变量声明空间分离"的典型体现。

这一技巧同样适用于模块场景：当从文件模块导入类时，import同时搬运类型与值，因此import后的名称既可作为类型注解也可作为值使用。

迁移旧 JavaScript 代码时的命名空间用法

结合文档"命名空间适合移植旧的 JavaScript 代码"的定位，一个典型的迁移路径是：

1. 存量 JS 阶段：已有大量(function(something) { ... })(something || (something = {}))形式的 IIFE 分组代码；
2. TS 直译阶段：将每个 IIFE 块改写为namespace块，something.xxx = ...改写为export xxx，通过跨文件合并保持原有对象结构不变；
3. 演进阶段：对于新代码与需要跨项目复用的代码，逐步迁移到文件模块（根级别export+ 显式import），最终由构建工具负责打包，而非依赖--outFile的全局顺序合并。

迁移期间若需要为尚无类型定义的第三方库快速补类型，可以使用declare module "some-library"声明全局模块（参见 docs/typings/ambient.md 与 docs/project/modules.md 的global.d.ts章节），让团队快速开始，不必为每个库都维护完整定义。

小结：命名空间与模块的选择决策

用一句话总结本仓库 docs/project/namespaces.md 的核心结论：命名空间是 JavaScript IIFE 分组模式的 TypeScript 语法糖，适合快速演示与移植旧代码；而大多数项目的代码组织，应以文件模块（外部模块）为主体，让显式依赖与构建工具替你管理全局作用域与编译顺序问题。

• 文档
• 教程