TypeScript 7 修复 union/intersection 合成属性的 setter 可访问性检查：读写权限分离解析-平芜编程栈

文档
教程

【免费下载链接】typescript-book

The Concise TypeScript Book: A Concise Guide to Effective Development in TypeScript. Free and Open Source.

项目地址：https://gitcode.com/gh_mirrors/typ/typescript-book

本文基于 typescript-book 仓库中的 TypeScript 新闻条目（2026 年 8 月 24 日发布），深入讲解 TypeScript 7 原生（native）检查器中一项关于类型可访问性的修复：在由 union 类型和 intersection 类型"合成"出来的属性上，setter（写）的可访问性从此与 getter（读）的可访问性分开记录、分开检查。读完本文，你能理解这类合成属性为何会绕过protectedsetter 限制、修复前后的具体行为差异，以及如何在自己的代码库中验证这一行为。

背景：TypeScript 7 原生检查器与这次修复的时间线

要理解这项修复，需要先了解它所处的版本环境。根据本仓库收录的TypeScript 7.0 发布公告，TypeScript 7.0 于 2026 年 7 月 8 日作为稳定版本发布，是第一个构建在 Go 语言原生 codebase 之上的 TypeScript 版本：其编译器和 language service 均迁移到原生代码，类型检查逻辑从 TypeScript 6 迁移而来，目标是保持既有类型语义的同时获得性能提升。该公告还说明，language service 同时迁移到了 Language Server Protocol（LSP），编辑器可以复用同一套原生基础设施。

而本文讨论的修复，正是在 TypeScript 7.0 发布之后合入原生 codebase 的一项检查器（checker）修正。仓库中的英文原版新闻条目与印尼语版本都指出，微软合并了一个修复，使得对于由 union 和 intersection 合成出来的属性，读访问与写访问的可访问性被分别保留。对应的上游变更是 TypeScript 的 pull request #63932，标题为FixgetDeclarationModifierFlagsFromSymbolExfor synthetic properties——也就是说，问题出在检查器获取符号声明修饰符标志（declaration modifier flags）的路径上：针对合成属性，写访问（setter）的修饰符信息没有被独立地反映出来。

该新闻条目在仓库的新闻索引中按时间线排列，位于 TypeScript 7.0 发布（2026-07-08）与 7.1 的 ambient 模块 import attributes 特性（2026-09-01）之间，恰好印证了"7.0 之后合入"这一时间窗口。

什么是"合成属性"：union 与 intersection 属性的读写语义

当 TypeScript 把多个对象类型组合成 union 或 intersection 时，组合后类型上的属性并不是某个类中真实存在的成员声明，而是检查器按成员名匹配、综合多个来源后"合成"出来的属性。这正是问题发生的位置。

考虑一个典型的类设计：getter 是public的（任何代码都能读），setter 是protected的（只有类内部及其子类能写）：

declare class C1 { get foo(): number; protected set foo(value: number); } declare class C2 { get foo(): number; protected set foo(value: number); }

这种写法在封装设计中很常见：对外暴露只读视图，把写入限制在类型体系内部。get和set虽然共享同一个属性名，但它们在类型系统里是两条独立的声明，各自携带各自的可访问性修饰符。仓库中《Class》一章在Get and Set与Access Modifiers两节中，正是分别讲解了get/set访问器的定义语法，以及private、protected、public三种修饰符对成员可见性的控制方式——本例正是"读公开、写受保护"这一模式的直接应用。

现在把这两个类组合成 union：

declare const c: C1 | C2; c.foo; // 合法：读访问是 public c.foo = 123; // 非法：写访问是 protected

对于c.foo这样的属性访问，检查器会从C1和C2两个来源中合成属性foo的类型。合成的正确语义应当是：

读：两侧 getter 都是public，所以通过 union 读取合法；
写：两侧 setter 都是protected，所以在类体系外部赋值应当报可访问性错误。

union 类型的背景知识可以在仓库《Union Type》一章中找到入门说明；而本修复涉及的是更细粒度的部分——合成属性的可访问性元数据如何从各成员来源正确聚合。

修复前的问题：setter 的可访问性被 getter 吞掉

新闻条目对旧行为的描述很明确：对于这些合成属性，setter 的可访问性可能被忽略，因为检查在效果上直接使用了 getter 的可访问性来判断整个属性的可访问性。

把这一机制套到上面的例子上就能看清漏洞：C1和C2的foogetter 都是public的，所以检查器在判断"能否访问c.foo"时拿到的是 public 级别的访问权限；而对赋值语句c.foo = 123，本应再去检查合成 setter 的可访问性（protected），但旧逻辑没有做这步区分——于是protected set foo的限制在穿过 union（同样适用于 intersection）之后被静默放宽，非法写入被放行了。

这是一个典型的"能力泄漏"：类型组合本应是保持各成员类型已有约束的，结果却因为可访问性信息的丢失而意外扩大（widen）了写权限。

修复内容：独立记录写可访问性

修复后的行为，按新闻条目的原文描述是：

The checker now records write accessibility separately. Readingfooremains valid, while assigning to it correctly reports an accessibility error.

即检查器现在将写访问的可访问性单独记录：读取foo依然合法，而对它赋值会正确地报告可访问性错误。

从源码结构看，问题定位在getDeclarationModifierFlagsFromSymbolEx这条获取符号声明修饰符标志的路径上（PR 标题即FixgetDeclarationModifierFlagsFromSymbolExfor synthetic properties）。从这一命名可以推断：该方法负责为某个符号提取其声明上的修饰符标志（包含public/private/protected等可访问性信息），而在合成属性场景下，它对 getter 声明与 setter 声明没有做区分，导致赋值检查拿到的标志实际上来自 getter 一侧。修复让读与写各自携带来自对应声明（getter / setter）的标志，从而让c.foo = 123这类语句能命中 setter 的protected约束并报出可访问性错误。

需要注意的边界：新闻条目本身没有给出具体报错文案，也没有覆盖"部分来源 public、部分来源 protected"这类混合场景下的最终语义；上述结论均以仓库收录的新闻条目与 PR 标题为依据。

为什么这个修复重要：守住封装边界

这条修复的价值在于守住类的封装契约。类作者常常有意地"读公开、写受限"——例如只读的状态快照、带不变量校验的写入入口、或只允许子类修改的内部状态。新闻条目对此的表述是：

Classes can intentionally expose public reads while restricting writes. The fix preserves that boundary when TypeScript combines object types into unions or intersections instead of accidentally widening write access.

换言之，当 TypeScript 把多个对象类型组合成 union 或 intersection 时，这个修复保证作者设定的写边界被完整保留，而不是被类型组合机制意外地放宽。对于大量使用组合类型（事件对象联合、多实现类的集合、A & B风格的能力叠加）的代码库，这类静默的写权限扩大尤其隐蔽：它不产生运行时错误，只会让本应被静态检查拦住的赋值"合法化"，削弱类型系统在重构时的保护作用。

可用性与升级建议

关于这项修复的落地情况，新闻条目给出了一条明确的注意事项：

该变更在 TypeScript 7.0 之后被合入原生 TypeScript codebase。原始资料没有指明包含它的稳定 npm 版本，因此建议在依赖此行为之前，先核对已安装版本的发布说明。

由此可以整理出几条实操建议：

不要假设 TS 7.0 稳定版已包含此修复。合入发生在 7.0 发布之后，具体进入哪个 npm 版本需要以官方 release notes 为准；
用一段最小用例回归验证。把前文的C1 | C2示例放进项目，确认c.foo = 123在当前版本上是否报可访问性错误，即可判断你所使用的版本是否包含修复；
结合 7.0 的兼容性约束评估升级。TypeScript 7.0 发布公告指出该版本暂不提供稳定的程序化 API，依赖 TypeScript 嵌入能力的工具链（如 Astro、Vue、MDX、Svelte 及当时的部分 Angular workflow）可能仍需 TypeScript 6；团队在评估升级到包含本修复的版本前，应先确认框架与工具链的支持情况。7.0 候选版公告也提到过类似的兼容包装（@typescript/typescript6包），升级路径上值得关注官方给出的配套方案。