React Native SVG 在 Vitest 测试环境中的模块导入问题解析

问题背景

在开发跨平台 React 应用时，很多团队会选择使用 React Native Web 技术栈来构建同时支持 Web 和 Native 的组件库。当项目中使用了 react-native-svg 这样的跨平台 SVG 组件库时，在 Vitest 测试环境中可能会遇到模块导入问题。

典型错误表现

开发者在测试环境中运行 Vitest 时，控制台会抛出以下错误：

SyntaxError: Cannot use import statement outside a module

错误信息指出 react-native-svg 的源代码似乎是一个 ES 模块，但却被打包成了 CommonJS 格式。同时，错误提示中还包含了对 react-native 模块的类似警告。

问题根源分析

这个问题的本质在于现代 JavaScript 模块系统（ESM）与传统 CommonJS 模块系统的兼容性问题。具体到 react-native-svg 的情况：

1. react-native-svg 的源代码使用了 ES 模块的 import/export 语法
2. 但在打包发布时可能没有正确配置模块类型
3. Vitest 作为现代测试工具，默认期望处理 ES 模块
4. 当遇到 CommonJS 模块时，解析就会出现问题

解决方案

经过社区实践，目前有以下几种可行的解决方案：

1. 直接引用模块内部路径

import Svg, { Path, Polygon } from 'react-native-svg/lib/module/ReactNativeSVG';

这种方法直接跳过了包的入口文件，引用内部已经转换好的模块文件。但需要注意：

• 需要额外添加类型声明
• 可能会影响原生端的兼容性

2. 配置 Vite 别名

在 vite.config.ts 中添加以下配置：

resolve: {
  alias: {
    'react-native': 'react-native-web',
    'react-native-svg': 'react-native-svg/lib/module/ReactNativeSVG',
  },
}

这种方法更为彻底，通过构建工具的别名功能统一处理模块引用问题。

3. 配置 Vitest 内联依赖

按照错误提示的建议，可以在 vitest.config.js 中添加：

export default {
  test: {
    server: {
      deps: {
        inline: ["react-native"]
      }
    }
  }
}

最佳实践建议

1. 对于跨平台项目，建议优先考虑方案2（Vite别名配置），因为它能统一处理开发和测试环境的问题
2. 如果项目中有大量 react-native 相关依赖，可以考虑方案3（Vitest内联配置）
3. 对于临时解决方案，可以使用方案1，但不推荐长期使用

总结

react-native-svg 在 Vitest 测试环境中的模块导入问题，本质上是现代前端工具链与传统 React Native 模块系统之间的兼容性问题。通过合理的构建工具配置，可以很好地解决这类问题，保证开发体验的一致性。