本文以packages/core/CHANGELOG.md为骨架，系统梳理 @nativescript/core 从 0.10 到 9.1.2 十余年间的核心能力演进，重点剖析 9.x 引入的跨平台 NativeWindow 窗口抽象、CSS 引擎增强与破坏性变更迁移路径，帮助开发者在升级版本时快速定位影响面并掌握新 API 的实战用法。

版本总览：一条贯穿十年的能力增长线

packages/core/CHANGELOG.md完整记录了 @nativescript/core（以及历史形态的 tns-core-modules）自 2015 年 0.10.0 以来的全部发布历史，截至本文写作时最新版本为9.1.2（2026-09-14）。把各个大版本的关键主题串联起来，可以看到一条清晰的能力演进脉络：

下文将按"近期版本的实操影响"和"历史里程碑"两个维度展开，其中 9.x 与 8.x 内容来自 CHANGELOG 中信息量最大的段落，值得每一位升级者仔细阅读。

9.1.0 的重磅：跨平台 NativeWindow 窗口抽象

9.1.0 引入了 CHANGELOG 标注为 ⚠️ 的cross-platform NativeWindow（scenes、multi-windows、iOS 改进 API、Android 同步支持），这是近年对应用生命周期模型影响最大的一次重构。它的核心思路是：把 iOS 的 UIScene / UIWindow 与 Android 的 Activity / Window 统一抽象为NativeWindow，让"窗口"成为生命周期与内容承载的一等对象。

在仓库中，该能力位于 packages/core/native-window 模块，由三个文件组成：

• index.ts 统一导出接口、基类与平台实现；
• native-window-interfaces.ts 定义事件常量与事件数据类型；
• window-base.ts 提供跨平台窗口基类，native-window.ios.ts 与 native-window.android.ts 分别承载 iOS/Android 实现。

从 native-window-interfaces.ts 可以清楚看到这套抽象的事件模型：NativeWindowEvents定义了窗口级事件（activate/deactivate、background/foreground、close、attached/detached、displayed、contentLoaded、orientationChanged、systemAppearanceChanged、layoutDirectionChanged），并分别保留了 iOS 场景事件（sceneWillConnect、sceneDidActivate等）与 Android Activity 事件（activityCreated、activityResumed、activityBackPressed等）。WindowEvents则在 Application 层暴露windowOpen、windowClose、primaryWindowChanged三个聚合事件。

破坏性变更与迁移清单（务必逐条核对）

CHANGELOG 在 9.1.0 段落给出了非常具体的迁移指引，升级时请按以下清单核对代码：

1. iOS 访问方式：NativeWindow.iosWindow更名为NativeWindow.ios，其window属性更名为uiWindow。迁移为win.ios?.uiWindow/win.ios?.scene。
2. Android 访问方式：NativeWindow.androidWindow更名为NativeWindow.android。迁移为win.android?.activity。
3. 事件载荷语义：SceneEventData.window现在就是NativeWindow，原生UIWindow移到了SceneEventData.uiWindow。任何window载荷键一律表示NativeWindow。
4. 窗口枚举：getWindows()现在按角色过滤，默认只返回application+embedded两类；要枚举所有注册表面需显式调用getWindows('all')。
5. 退出事件语义：Android 上exit事件只在最后一个窗口结束时触发（此前任何 activity 结束都会触发）；iOS 的exit语义不变（进程终止）。
6. 生命周期归属：场景模式下 Application 的suspend/resume反映整个应用状态，追踪单个窗口请使用窗口的background/foreground事件。
7. detached 代替销毁：场景断开与 activity 重建现在触发detached而非销毁窗口；窗口保持注册状态、监听器存活，同一实例会在再次attached时复用。
8. 关闭后不可复用：窗口在close之后会清空全部事件监听器，不要复用已关闭的窗口实例。
9. CSS 根类变化：CSSUtils.getRootViewCssClasses()不再包含 orientation、appearance、direction 类——这些已变为按窗口维度，请改从窗口实例读取。

已弃用与已转正 API

• 已弃用（仍可用）：launch事件（改用ready+setWindowContentResolver()）、shouldDelayLaunchEvent（现在是 no-op）、Application.orientation()/systemAppearance()/layoutDirection()（委托给primaryWindow）、枚举类 getter（getAllWindows、getAllScenes、getWindowScenes、getPrimaryWindow、getPrimaryScene）。
• 转正（Un-deprecated）：Application上的activity*/scene*桥接 API 成为永久聚合 API——它们对每个窗口都会触发，通过args.window区分具体窗口。

窗口内容的供给通过WindowContentResolver完成（见 native-window-interfaces.ts）：它接收一个WindowContentRequest（含isPrimary标志、平台数据载荷），可返回View、NavigationEntry或模块名来设置窗口内容，返回null表示由调用方异步接管，返回undefined则回退到应用主入口。

9.x 错误处理策略：uncaughtErrorPolicy 取代 discardUncaughtJsExceptions

9.1.0 将uncaughtErrorPolicy类型化，并正式弃用discardUncaughtJsExceptions（关联 #11356）。在仓库的 config/config.interface.ts 中可以看到当前配置形态：

uncaughtErrorPolicy?: UncaughtErrorPolicy; // 旧字段：仅当取值为 true 时等价于顶层 uncaughtErrorPolicy 的抑制行为 discardUncaughtJsExceptions?: boolean;

注意 CHANGELOG 与类型注释中给出的语义细节：旧的discardUncaughtJsExceptions: true会抑制uncaughtErrorPolicy: 'throw'的崩溃行为；而false并不会恢复旧有的"未捕获即崩溃"行为——需要显式设置uncaughtErrorPolicy: 'throw'。升级时建议把所有discardUncaughtJsExceptions配置替换为等价的uncaughtErrorPolicy取值。

9.x CSS 能力扩展：连续圆角、尺寸上限与 flexbox 间距

9.1.0 之后的若干版本集中补齐了一批贴近 Web CSS 的布局与样式能力，且都有源码直接支撑：

• corner-shape（iOS 连续圆角）：corner-shapeCSS 属性用于 iOS 的 continuous corners。实现上，ui/styling/background-common.ts 定义了cornerShape字段（默认round），ui/styling/background.ios.ts 在原生侧将其映射为kCACornerCurveContinuous（squircle）或kCACornerCurveCircular。style-properties.spec.ts 中有对应测试，验证cornerShape默认值与squircle取值在 Style/Background 上的联动。
• max-width / max-height：9.1.0 起核心支持max-width与max-heightCSS 属性，类型为PercentLengthType（见 ui/styling/style/index.ts）。
• flexbox gutters：9.1.0 起支持 flexbox 的row-gap/column-gap（见 ui/styling/style/index.ts）。
• 方向属性：9.0.0 支持了 style 的direction（ltr/rtl）属性；layoutDirectionChanged事件随之成为窗口级事件。
• 多阴影 box-shadow：9.0.0 起支持多个 box-shadow 叠加（此前 8.6.1/8.6.2 已修复none处理与解析边界）。

9.x 构建与平台：vite 纯 JS 支持、runtimePackageName 与平台 SDK 更新

• vite 支持纯 JavaScript（9.1.2，关联 commit d0f3e7654）：vite 工作流在原有 TypeScript 基础上补齐了纯 JS 项目的支持，相关信息同步记录在 packages/vite/CHANGELOG.md。9.0.0 时 @nativescript/vite 即作为正式特性进入核心发布（关联 #10948）。
• runtimePackageName 配置项（9.1.0）：向IConfigPlatform增加了runtimePackageName字段（见 config/config.interface.ts），用于在配置层面指定运行时包名。
• 平台类型与 SDK：9.1.1 带来 iOS 26.5 类型与 Android API Level 36 + 37 类型；9.0.0 引入 iOS 26 类型（含 ActionBar、Switch 改进）以及.ns-{platform}-{sdkVersion}的 CSS 根作用域类；Android 侧 9.0.0 支持 API Level 35+ 的OnBackPressed处理与 edge-to-edge 工具（enableEdgeToEdge、setStatusBarColor、setNavigationBarColor、setDarkModeHandler）。
• UI 组件：9.0.0 起 TabView 在 iOS 18+ 使用 UITab 并支持 search role；iOS SplitView 成为正式组件（9.0.0 引入、9.0.9 完善布局与生命周期）；ListView 获得 sticky headers、sectioned data 与自动隐藏搜索栏；TextField 支持decimal键盘类型与 CSSwhite-space/text-overflow。
• Shared Element Transitions：8.5.0 起支持共享元素转场，9.1.0 持续改进 iOS 交互式 morph 关闭（cornerRadius/alpha 修复）。

8.x：CSS 引擎与事件系统的里程碑

8.x 是 CSS 能力爆发期，这部分演进直接奠定了 9.x 的样式基础：

• 解析器更替：8.8.x 期间 css-tree 成为默认解析器（6.4.0 引入可选支持），8.8.0 引入 css-what 解析器并支持 Level 4 选择器:not()、:is()、:where()与~兄弟选择器，同时带来CSS media query 支持（此前 8.9.x 又在 ruleset 中缓存 media query 数组以提升性能）。
• 值与函数：8.9.x 支持 CSS wide keywords、color-mix()、calc()中的 infinity 值；8.x 期间 CSS variables 与嵌套calc()得到完整实现，8.2.5 起支持移除指定 CSS 变量。
• 框架集成：8.9.0 支持 Tailwind v4，并为style属性模块做了重组。
• 事件系统收敛：8.8.0 移除复数事件/手势名称与 GestureTypes 枚举作为 eventName 的用法，事件回调参数强制使用类型化的事件数据对象（如OrientationChangedEventData），统一once监听器语义；8.5.0 起WeakRef在 Android/iOS 统一使用deref。
• 运行时与平台：8.9.0 支持 Node-API 引擎与 winter-tc；8.8.0 起可将核心嵌入既有原生宿主工程（embed）；9.0.0 前的 8.5.x 还引入了 Swift Package Manager 配置支持与多 target 的 Swift 包支持。

更早版本的关键断点（升级路径参考）

• 7.x：7.0.0 起以 es2017 为编译目标，引入nativescript.config配置文件；7.3.0 移动BottomNavigation/Tabs至 @nativescript-community（破坏性变更）；AndroidTransitionType并入Transition类静态成员；7.1.0 增加 Frame 的navigatingTo/navigatedTo事件与queueMacroTask。
• 6.x：6.2.0 引入 scoped packages、系统外观（暗黑模式）属性/事件与 CSS 类、HSL/HSLA 支持；6.3.0 起支持requestAnimationFrame、模态框系统 CSS 类与可选 css-tree parser；6.5.x 完善手势、Span 垂直对齐与文件系统复制 API。
• 5.x：5.4.0 增加 elevation 阴影、activityNewIntent事件；5.0.0 起核心框架迁移至 Android Support Library（Activity 继承AppCompatActivity、Fragment 继承support.v4.app.Fragment），iOS 原生视图改为加入可视树时才创建（请在loaded事件中访问nativeView）；ContainerView 系组件默认溢出安全区。
• 4.x：4.0.0 移除Layout基类（改用LayoutBase）、application.start()迁移到run()、showModal收敛为 options 对象签名；4.2.0 引入 Flexible Error/Exception 处理；4.x 还带来 box-shadow/text-shadow、RootLayout 动态分层 API 与一等公民的无障碍支持。
• 更早（1.x-3.x）：确立导航事件四件套（navigatingTo/navigatedTo/navigatingFrom/navigatedFrom）、手势系统、模态链、ActionBar 结构，以及 CSS 状态选择器、Flexbox 布局、CSS3 动画与过渡等基础能力；1.0.0 时Image.url→src、local-settings→application-settings等命名收敛完成。

如何核对与跟进升级影响

升级到 9.x 时，最权威的核对对象就是本 CHANGELOG 本身（packages/core/CHANGELOG.md），建议按以下路径操作：

1. 通读你当前版本到目标版本之间所有标注 ⚠️ 或 BREAKING CHANGES 的段落，逐条对照上文列出的迁移清单（尤其 NativeWindow 相关九条）。
2. 对每个被改动 API，直接到 packages/core 对应模块核对类型定义，例如窗口事件模型看 native-window/native-window-interfaces.ts，配置项看 config/config.interface.ts，样式属性看 ui/styling/style/index.ts。
3. 需要确认行为细节时，仓库中带.spec.ts的文件（如 native-window.ios.spec.ts、native-window.android.spec.ts、style-properties.spec.ts）提供了可验证的行为契约。
4. 关注每个版本的 "Thank You" 段落的维护者动态，以及### 🔥 Performance段落——9.1.0 对 CSS matching/cascade/application 的整体重构（关联 #11361）和 media query 数组缓存（#11309）提示：升级后若涉及大量动态样式，可留意渲染性能的正面或负面变化。

小结

从packages/core/CHANGELOG.md可以完整读出 @nativescript/core 的十年演进：它把 CSS 能力从基础属性一路推进到 media query、color-mix、连续圆角与 flexbox gutters；把窗口模型从单窗口起步推进到 iOS/Android 统一的NativeWindow抽象；把构建链从 webpack 演进到 vite 并支持纯 JS 工程；同时通过大版本的破坏性变更清单，为升级者留下了清晰可执行的迁移路径。对计划升级到 9.x 的团队，NativeWindow 迁移清单与uncaughtErrorPolicy配置替换是两项最优先核对的事项。