React Native SVG 组件导入错误的解决方案与最佳实践

问题现象分析

在 React Native 项目中集成 react-native-svg 组件时，开发者可能会遇到以下错误提示： "Element type is invalid: expected a string (for built-in components) or a class/function (for composite components) but got: number"

这种错误通常发生在以下环境组合中：

• React Native 0.72.7 或 0.73.6 版本
• react-native-svg 15.x 版本
• 配合使用 react-native-svg-transformer 1.5.0 版本
• 在 iOS 或 Android 平台上都可能出现

根本原因探究

经过技术分析，这个问题主要源于 SVG 文件导入方式的配置不当，而非 react-native-svg 组件本身的问题。具体表现为：

1. 模块解析异常：SVG 文件被错误地解析为数字或对象而非 React 组件
2. 热更新不稳定：部分开发者反馈问题在多次重载后可能暂时消失
3. 新旧架构兼容性：在 React Native 的新架构(Fabric)下表现更为明显

解决方案详解

配置修正方案

在 metro.config.js 文件中，关键配置项需要特别注意：

// 正确配置示例
const { getDefaultConfig } = require("expo/metro-config");

module.exports = (() => {
  let config = getDefaultConfig(__dirname);
  
  config.transformer = {
    ...config.transformer,
    babelTransformerPath: require.resolve("react-native-svg-transformer")
  };
  
  config.resolver = {
    ...config.resolver,
    assetExts: config.resolver.assetExts.filter(ext => ext !== "svg"),
    sourceExts: [...config.resolver.sourceExts, "svg"]
  };

  return config;
})();

特别注意以下要点：

• 使用 require.resolve("react-native-svg-transformer") 而非其他变体路径
• 确保正确处理了 assetExts 和 sourceExts 配置
• 在 Expo 环境中需要额外考虑兼容性处理

导入方式优化

推荐使用以下两种导入方式：

1. CommonJS 方式（兼容性更好）

const WarningIcon = require('@assets/icons/warning-icon.svg').default;

2. ESM 方式（需要确保配置正确）

import WarningIcon from '@assets/icons/warning-icon.svg';

进阶建议

1. 环境检查清单：

   • 确认 react-native-svg 和 react-native-svg-transformer 版本兼容
   • 检查 metro 缓存是否清理干净（可尝试 npx react-native start --reset-cache）
   • 在 Expo 项目中确认是否使用了预构建版本

2. 架构适配建议：

   • 对于新架构项目，建议使用最新稳定版的 react-native-svg
   • 考虑将 SVG 组件封装为独立模块，提高复用性

3. 调试技巧：

   • 在出现问题时，先 console.log 检查导入的对象结构
   • 尝试将 SVG 文件内容简化，排除复杂 SVG 导致的解析问题

最佳实践总结

1. 统一配置管理：将 SVG 相关配置集中维护，避免散落在多个配置文件中
2. 版本锁定：在 package.json 中精确指定相关依赖版本
3. 渐进式集成：先在小范围模块中测试 SVG 导入功能，确认稳定后再扩大使用范围
4. 文档维护：团队内部记录特定项目的 SVG 处理方案，方便新成员快速上手

通过以上方案，开发者可以系统性地解决 React Native 项目中 SVG 组件导入异常的问题，并建立起稳健的矢量图形处理方案。