#兼容性

本文主要介绍如何确保 Bundle 和 Lynx Engine 之间的版本兼容性，以及如何应对 Lynx Engine 版本演进带来的挑战。

#从源码构建

一种简单的保证兼容性的方法是，永远同时从源码构建 Bundle 和宿主应用。

• Bundle 可以充分利用当前 Lynx Engine 版本的所有特性
• 在开发阶段就能完全确保兼容性，所见即所得

#多版本兼容

但是在一个复杂的工程中，Bundle 和 Lynx Engine 之间并非一一对应的关系

• 一个 Bundle 可能运行在多个含有不同版本 Lynx Engine 的应用中

• 一个应用中也可以运行多个由不同团队维护的 Bundle

此时，需要为 Bundle 设置引擎版本（engineVersion）来保证兼容性

例如：一个 engineVersion 为 3.3 的 Bundle 可以在 Lynx Engine 3.3 及以后的版本上运行，但不能在 3.2 上运行。

在一个 Bundle 对应多个 Lynx Engine 版本的情况下，该 Bundle 的 engineVersion 必须小于所有 Lynx Engine 的版本。

在一个 Lynx Engine 版本上运行多个 Bundle 的情况下，每个 Bundle 都可以设置不同的 engineVersion，但是都不能大于 Lynx Engine 的版本

#版本不兼容处理

当 Bundle 尝试在一个较低版本的 Lynx Engine 上运行时，系统会抛出错误码为 10204 的 Fatal 级别错误，并停止渲染流程。这种机制可以防止不兼容版本导致的潜在运行时问题。

#设置引擎版本

engineVersion 是一个含有两位版本号的字符串，可以在配置文件中指定：

import { defineConfig } from '@lynx-js/rspeedy';
import { pluginReactLynx } from '@lynx-js/react-rsbuild-plugin';

export default defineConfig({
  plugins: [
    pluginReactLynx({
      engineVersion: '3.2',
    }),
  ],
});

#升级 Lynx Engine

Lynx Engine 的迭代过程中，会有新增功能，也会有废弃功能，它们的兼容性也由 engineVersion 来保证。

#新增功能

一些新增功能不会对已有的 Bundle 产生影响，但如果 engineVersion 小于其被引入的版本，则需要在运行时进行判断，例如：

// Detect if `lynx.newlyAddedMethod` can be called
if (lynx.newlyAddedMethod) {
  lynx.newlyAddedMethod();
}

而一些新增功能完全无法运行在低版本的 Lynx Engine 中，因此它们只有在 engineVersion 大于或等于对应版本时才会被启用。

#废弃功能

一些功能也可能在迭代的过程中被废弃，他们的行为可能在设置了更高的 engineVersion 后发生改变。

• 如果只升级 Lynx Engine 的版本，不升级 Bundle 的 engineVersion，那么不会有兼容性问题产生
• 如果同时升级了 Lynx Engine 和 Bundle 的 engineVersion，需要阅读 CHANGELOG 来确保没有产生预期外的行为变更

#兼容性表格

Lynx 为每个 API、内置元件及 CSS 属性都提供了兼容性表格，以 gap 属性为例：

LCD tables only load in the browser