typescript 命名空间自2026年起不推荐用于业务代码，其核心作用是逻辑分组与作用域隔离，适用于声明文件、全局类型增强及快速原型，但es模块才是大型项目的标准方案。
在 TypeScript 中，命名空间（namespace）曾是组织大型项目代码的重要手段，但2026 年起已不推荐在业务代码中使用它来组织项目结构。它的设计初衷是解决早期浏览器无模块系统时的全局污染问题，如今已被现代 ES 模块（ESM）全面取代。不过，理解其原理和适用边界，对维护旧项目、编写声明文件或特定场景仍有实际价值。
命名空间的核心作用：逻辑分组与作用域隔离
命名空间本质是一个自执行函数包裹的命名空间对象，所有未 export 的成员都私有，仅暴露的成员可通过点号访问：
-
避免全局冲突：比如多个团队都定义
Validator类，放在Validation.Email和Validation.Phone下互不干扰 -
层级化组织：支持嵌套，如
Utils.IO.File.read()，适合工具库内部结构划分 - 编译后无运行时开销：TS 编译为 IIFE，不依赖加载器，适合直接注入 HTML 的脚本场景
多文件命名空间：仅限声明合并场景
通过 /// <reference path="..."></reference> 可跨文件扩展同一命名空间，常见于：
-
第三方库的类型声明补充：例如为 jQuery 插件添加新方法签名到
jQuery.fn -
测试工具链代码：如 TS 内部的
src/harness/目录仍用此方式聚合调试工具 -
单页应用中多个
<script></script>标签共用逻辑：但这类场景现在更倾向打包工具统一处理
⚠️ 注意：这种写法破坏模块树结构，Vite、Rspack 等构建工具无法对其做 Tree-shaking，会增大产物体积。
替代方案：ES 模块才是大型项目的标准路径
现代 TypeScript 大型项目应完全基于 ESM：
-
按功能拆分文件：如
user/types.ts、user/service.ts、user/index.ts统一导出 -
利用
export type隔离类型：类型只参与编译，不进入 JS 输出，提升构建效率 -
路径别名 +
baseUrl+paths：在tsconfig.json中配置@models/*映射，避免深层相对路径 -
统一类型入口：在
types/index.ts中集中 re-export 公共接口，供全项目导入
什么时候还能用命名空间？极少数合理场景
并非完全废弃，但使用范围非常窄：
-
编写
.d.ts声明文件：为没有 ESM 支持的旧库补全类型，需用declare namespace -
定义全局增强类型：如
declare global { namespace NodeJS { interface ProcessEnv { CUSTOM_FLAG: string; } } } - 快速原型或教学示例：无需构建流程，直接在 HTML 中引入多个 TS 文件时临时组织
业务代码中若出现 namespace，多数是历史包袱或误用 —— 它不能替代模块职责，也不支持按需加载和依赖分析。
