TypeScript私有字段与#语法：编译时隐私还是运行时隐私
对比 TypeScript 的编译时 `private` 修饰符与 ECMAScript 的运行时强制字段 `#`，帮助您为 2026 年的代码库选择合适的封装策略。
TypeScript 项目中大多数与隐私相关的缺陷，都源于将两种实际上工作原理不同的封装模型混为一谈：仅由编译器处理的 private 关键字，以及 ECMAScript 中在运行时生效的 # 字段语法。团队们常常不加深思就选择其中一种方式并将其投入使用，之后却会遇到该选择以意想不到的方式失效的情况。
一旦代码开始运行，TypeScript 的 private 关键字就无法提供任何保护。编译器在您编写和构建项目时会检查成员的可见性，但它生成的 JavaScript 代码会将所有的 “private” 成员都转换为普通的公共属性。任何使用该编译后输出结果的代码都能完全绕过访问修饰符的限制。
ECMAScript的#字段采用了不同的方式来实现真正的隐私保护。运行时通过将字段数据存储在内部的WeakMap中来强制界定边界，因此外部代码无法访问这些数据。这一保障能防止意外滥用，即便在不可完全信任的环境中也能保护敏感信息的安全。
选择这两种方式中的哪一种，决定了代码投入生产后封装机制是否依然有效，正因如此，正确处理这个问题至关重要。
关键要点
- TypeScript的
private修饰符在编译过程中会被移除，仅留下可被自由访问的普通JavaScript属性。而ECMAScript的#字段则借助基于WeakMap的存储机制，即使在转译之后仍能保持隐私性。
private。而在发布库、处理动态导入或需要防止敏感值在运行时被查看时，则应使用 #。private 改为 # 会改变公共 API 的外观，还可能破坏那些依赖反射功能的工具。如果没有明确的规范，代码库中就会混用这两种方式且缺乏一致性。private，只是因为它与 Java 等语言中的模式相似，但当仅有 JavaScript 能使用该类型的场景完全忽略这一约定时，他们就会措手不及。由此产生的错误往往难以察觉，但排查起来却十分耗时。理解TypeScript的private修饰符：仅限编译时使用
TypeScript中的private关键字纯粹是类型系统的一种构造。它在开发阶段可阻止未经授权的访问，但一旦编译完成，生成的JavaScript代码中就会包含普通的、无保护的属性。实际上，private函数更多是作为文档辅助工具，而非真正的安全屏障。
当包含 private 字段的类被编译为纯 JavaScript 代码后，该访问修饰符会完全消失，该字段便变成普通属性，任何使用者都可以直接读取或覆盖它。在三种情况下这会带来真正的问题：将代码包发布到 npm、动态导入第三方模块，或与序列化工具、ORM 等基于反射的工具有集成。
简洁性正是 private 的主要优势。来自 Java 或 C# 等语言的开发者能立刻理解它的作用。编辑器会隐藏私有成员，不显示自动补全建议；重构工具会尊重预定的访问级别；编译器则会在开发及代码审查过程中检测到意外暴露的情况并给出提示。
当对运行时的假设被证明是错误时，问题就出现了。想象一个团队在假定所有使用他们代码的程序都会运行 TypeScript 的前提下构建内部控制面板。数月后，一个用 Python 编写的服务加载了编译后的 JavaScript 包，并开始直接修改会话令牌。原本设想的隐私边界在编译器之外根本不存在，因此根本无法起到任何防护作用。
只要你能控制整个依赖链并且从始至终都强制使用 TypeScript，这种模式就能正常运行。但一旦代码跨越了语言边界或被发布到公共场合，“私有”就不再是一种保障，而仅仅是个建议而已。
ECMAScript 私有字段（#）：运行时强制实现的强隐私保护
以 # 开头的字段是 JavaScript 的原生特性，能够创建真正无法从类外部访问的属性。引擎会将它们存储在内部的 WeakMap 中，从而隐藏起来，既不会被反射机制发现，也不会被任何试图访问它们的外部代码获取。当目标环境为 ES2022 或更高版本时，TypeScript 会在输出结果中保留 # 语法不变。
在为现代目标环境编译时，生成的 JavaScript 会原样保留 # 语法，而不会将其转换为普通属性。这里的封装性由运行时本身保证：在严格模式下，试图从类外部访问如 wallet.#balance 这样的字段会引发语法错误。即便调用 Object.keys(wallet)，也会返回空数组，因为私有字段完全不在常规的属性枚举机制范围内。
# 字段的弊端在于兼容性问题。若要支持 ES5 或 ES2015 等较旧的环境，TypeScript 就不得不生成基于 WeakMap 的填充代码，这会增加打包体积及每次访问时的开销——对于那些面向对性能要求较高的浏览器环境的库来说，这是一个亟需解决的难题。
此外还有开发者体验方面的问题。编辑器无法为类外的 # 字段提供自动补全功能，而且某些调试工具默认会隐藏这些字段，不让对象检查器看到。像 JSON.stringify 这样的序列化工具也会默默跳过私有字段，这会让那些期望获取对象完整状态信息的开发者感到意外。
私有字段在三种情况下最为适用：保护加密密钥或访问令牌，防止 API 使用者篡改内部不变量，以及在无法完全信任其他代码同时运行的环境中执行代码。在这些场景下，强大的运行时保障比所放弃的便利性更为重要。
对比分析：不同方法的适用场景
选择使用 private 还是 # 最终取决于你的信任边界和工具需求——并没有一种方法在所有情况下都是正确的默认选择。因此，团队应制定明确的规则，而非仅凭直觉选择最熟悉的方式。
以下情况适合使用 TypeScript 的 private：
- 你正在构建一个内部应用程序，且所有使用该应用的代码都是在严格编译设置下的 TypeScript 代码。
# 字段填充机制会大幅增加代码包的大小。在以下情况下可使用 ECMAScript # 字段：
- 您正在向 npm 发布软件包，且无法确保所有使用者都会遵守仅使用 TypeScript 的规范。
- 您正在存储认证令牌、加密密钥或支付信息等敏感数据，这些数据不应被他人查看。
- 您正在构建插件系统，而不可信的第三方代码需要与您的代码在同一个运行时环境中执行。
当设计同时需要反射支持与真正的运行时隐私保护时，就会出现冲突。典型的情况是：ORM试图枚举所有字段以构建数据库映射，但带有#标记的字段却不会出现在该枚举结果中。解决此问题通常需要添加显式的获取器方法或元数据装饰器，而这会增加复杂性，许多团队都希望避免这种情况。
测试又带来了新的问题。在 TypeScript 的 private 关键字作用下，同一项目中的测试文件仍可通过类型断言访问内部状态。而使用 # 字段时，通常需要将可测试的行为提取到单独的方法中，或依赖注入机制。那些习惯在测试时直接操作私有内部结构的团队往往觉得这种额外的限制十分烦人。
截至 2026 年，# 字段在那些对安全性要求较高的库中越来越常见，而 private 修改符则依然是内部应用程序代码的常规选择。TypeScript 5.7 已将这两种方式都视为完全支持的一流特性，具备自动推断和错误检查功能，因此选择哪种方式实际上取决于架构设计而非编译器的能力。
实际代码示例：两种模式的实现
在同一个生产代码库中，出于不同目的同时使用这两种模式是很常见的。关键在于在特定范围内保持一致性：将private用于普通的实现细节，而将#保留给与安全相关的字段。
以一个类为例，它有一个标记为private的requestCache字段，以及一个标记为强私有级的#authToken字段。requestCache仍保持为private，因为测试和调试工具需要能够查看它，而且如果将来有用的话，序列化工具也能读取它。而#authToken则属于强私有级，因为在运行时暴露它会造成真正的安全漏洞。
当不同字段具有不同的风险等级时，将两者混合使用是合理的。诸如配置值和缓存之类的内容属于内部细节，适当的一些灵活性并无问题。而凭证和加密密钥则需要更强的运行时保障。
另一个实际的例子是状态机，它将转换规则设为private访问权限，同时用#隐藏实际状态。该状态机仅通过getState()方法暴露状态，而将底层的#currentState字段置于不可访问范围，从而防止外部代码直接修改它。validTransitions映射表也作为private字段存在，因为测试套件可能仍需要检查规则集以处理边界情况。
这种约定具有较好的扩展性。例如，一个包含50个类的代码库中，大约10个与认证相关的类会使用#字段，而其他所有类则仍采用private修饰。在代码中看到#时，就能明确表明已进入安全敏感区域。
迁移策略与团队约定
将一个类从private改为#，从其公开接口的角度来看属于破坏性变更。任何依赖枚举属性的工具都会停止正常工作，因此这类迁移需要精心规划，并逐步实施，同时协调所有使用受影响代码的团队。
将一个类从private改为#字段通常遵循一定的顺序：
- 审查哪些字段确实需要运行时强制的隐私保护，哪些字段仅需要进行编译器级别的可见性检查。
- 取消原定公开该公共 API 变更的正式版本发布。
- 在专门的特性分支中，将那些对安全性至关重要的字段转换为
#语法格式。 - 重新设计内部测试，使其不再依赖直接访问这些字段的方式。
- 确认序列化库和 ORM 在更新后的字段结构下仍能正常工作。
- 发布版本时附上详细说明，明确指出出现了哪些问题及其原因。
内部代码库在此方面更为轻松。由于无需考虑外部使用者，团队可以逐步推出变更，而无需追踪语义版本号。真正的难点在于协调：开发人员需要对何时必须使用#、何时仍可使用private有统一的认识。
许多团队采用的实用惯例如下：
- 将
#保留用于身份验证令牌、加密密钥、数据库凭证以及个人可识别信息。 - 将
private用于缓存层、配置状态、内部状态机以及派生或计算得到的值。 - 在代码审查清单和入职文档中写明相关规则，以便新员工快速掌握。
private 而非 # 声明的密码字段。在同一个代码库中同时维护 TypeScript 和传统 JavaScript 的组织需要稍有不同的规则集。在将 TypeScript 服务与较旧的 JavaScript 模块结合在一起的单一代码库中，由于不必要的代码也会因此产生转译开销，所以无法在所有地方都使用 # 字段。在这种架构下，划分标准通常在代码库或包层面：新编写的 TypeScript 模块会对敏感数据使用 #，而传统的 JavaScript 模块则保持原样，直到最终被重写为止。
类似这样的混合策略可见于那些在部分服务中采用严格的运行时隐私保护机制，而在其他服务中则使用类型级契约的分布式系统中：某些组件会实施严格的封装机制，而其他组件则完全依赖编译器检查。
大多数迁移问题都源于将代码转换视为纯粹的机械式查找替换操作。如果在未先检查该字段的所有使用方的情况下就将private替换为#，就会导致隐性故障。以一个基于反射机制的日志记录工具为例，它通过遍历对象的属性来生成调试信息——一旦这些属性变成#类型的字段，它们就会从枚举中消失，导致日志记录器无法再获取对象的运行状态。正确的解决方式是通过明确的getter方法或结构化的日志接口来暴露所需数据，而非依赖反射机制来查看私有内部信息。
常见问题
我可以在同一个类中同时使用private修饰符和#类型字段吗？
是的。TypeScript 5.7及更高版本允许在同一个类定义中同时使用这两种机制。常见的做法是将private用于那些测试或调试工具仍可能需要访问的实现细节，而将#保留给那些必须避免任何形式运行时检查的少数字段。编译器会将它们视为两个独立但兼容的可见性系统来处理。
#字段在IE11这样的旧版JavaScript环境中可行吗？
并非直接支持。当构建目标为 ES5 或 ES2015 时，TypeScript 编译器会退而使用基于 WeakMap 的填充代码来模拟 # 字段的行为，这会增加额外的代码体积并带来运行时性能开销。如果仍需支持旧版浏览器，最好继续使用 private 修饰符，并接受仅在编译时生效的约束，而非承担填充代码带来的额外负担。
在 JSON 序列化过程中 # 字段会发生什么？
JSON.stringify以及类似的序列化工具根本无法识别#字段，因此包含这些字段的任何对象在序列化时都会完全缺失这些属性。如果需要让输出中体现部分私有状态，就必须刻意将其暴露出来——要么通过getter方法，要么通过定义自定义的toJSON实现来精确控制要包含的内容。
子类可以访问父类的#字段吗？
不。ECMAScript的私有字段仅属于声明它们的类，这一界限是绝对的——子类无法读取或修改父类的#字段，甚至无法通过受保护或公共方法间接实现。这与private修饰符有明显区别，因为TypeScript编译器有时会允许通过显式的类型断言让子类访问这些字段。
我应该将现有的代码库从private字段迁移到#字段吗？
只有在存在实际需求时才应进行迁移——比如真正的安全漏洞，或是确实需要运行时保障隐私。由于此次迁移会带来影响工具、序列化行为及测试设计的重大变化，绝非可以随意处理的事情。对于大多数内部应用而言，private修饰符已经能够提供足够的封装性，因此无需承担迁移成本。应优先将共享库、面向公众的API以及处理敏感数据的模块作为迁移对象。
2026年为您的代码库选择合适的隐私模型
在 TypeScript 的 private 字段与 ECMAScript 的 # 字段之间做选择并非随意偏好问题。这一抉择决定了封装机制能否在编译器之后依然有效，影响外部代码与类的交互方式，同时也能向后续维护代码的人传达架构设计意图。
当您能够掌控完整的依赖关系图，并且更重视开发者工具而非严格的运行时保障时，应使用 private。而当代码在不可信环境中运行，或需要处理绝不能通过反射暴露的数据时，则应选用 #。实际上，大多数真实项目都需要结合两者使用，具体选择需根据每种字段所代表的含义来决定。
如果这个决策出错，往往会在实际运行中显现出来：由于意外修改导致不变量被破坏，凭据通过日志记录机制泄露，或者测试套件根本无法验证内部状态。只要制定明确的规范和文档化的架构规则，所有这些问题都是可以避免的。
开发内部工具的团队通常可以依赖private修饰符，并利用围绕它构建的成熟工具。而那些发布公共库或在安全要求较高的领域工作的团队，则需要#字段所提供的运行时保障。在当前的TypeScript生态系统中，这两种模式都得到了同等良好的支持——具体选择取决于你的威胁模型以及你对API使用者的信任程度。
相关阅读
- Node.js 对 TypeScript 的原生支持究竟能做什么和不能做什么 — 本文介绍了 Node.js 如何通过类型剥离功能以原生方式运行 .ts 文件，为何会跳过类型检查，以及何时仍需要真正的构建步骤。
- React 设计模式：从传统面向对象到现代 Hooks — 阐述了 Singleton、Factory、Observer 等传统软件设计模式在 React 中的应用，以及 HOC、Hooks、复合组件等 React 特有的设计模式。