React Native Skia 中 Web 模块导出问题的分析与解决

在 React Native Skia 1.11.7 版本中，开发者在使用 Vite/ESBuild 构建 Web 项目时遇到了一个模块导出问题。这个问题表现为构建工具报错，指出 NativeSkiaModule.web.js 文件没有导出 "default" 默认导出项。

问题背景

React Native Skia 是一个高性能的 2D 图形库，它允许开发者在 React Native 应用中实现复杂的图形渲染。该项目采用了平台特定的模块系统，其中 NativeSkiaModule.ts 文件用于原生平台，而 NativeSkiaModule.web.ts 文件则专门用于 Web 平台。

问题本质

问题的核心在于模块导出不一致性：

• NativeSkiaModule.ts 文件中包含了一个默认导出
• 但对应的 Web 版本 NativeSkiaModule.web.ts 却没有提供默认导出

这种不一致性在使用 ESBuild（Vite 的底层构建工具）时会引发错误，因为 ESBuild 会进行静态分析，严格检查模块的导出情况。相比之下，Metro（React Native 默认的打包工具）采用更宽松的策略，只在运行时检查模块导出，因此不会出现构建错误。

技术细节

在模块系统设计中，保持平台特定文件接口一致性非常重要。当开发者通过 import 语句导入模块时，构建工具会：

1. 解析导入路径
2. 根据平台后缀选择正确的文件（如 .web.ts）
3. 检查导出是否符合预期

ESBuild 的严格检查机制能够提前发现这类接口不一致问题，这实际上是一个有价值的特性，可以帮助开发者及早发现潜在的跨平台兼容性问题。

解决方案

修复方案相对直接：确保 Web 版本的模块也提供默认导出。具体做法是在 NativeSkiaModule.web.ts 中添加：

export default {};

虽然这个默认导出在实际运行时可能不会被使用，但它满足了构建时的静态检查要求，保持了接口一致性。

经验总结

这个案例给我们几点启示：

1. 跨平台库开发时，应保持平台特定文件的接口一致性
2. 不同构建工具对模块系统的处理方式可能有差异
3. 严格静态检查虽然可能增加初期开发成本，但有助于提高代码质量
4. 空对象导出可以作为临时解决方案，但长期应考虑更明确的接口设计

React Native Skia 团队在 1.11.8 版本中迅速修复了这个问题，体现了对社区反馈的积极响应。对于开发者而言，及时更新依赖版本是解决此类问题的最佳实践。