集成React Native到现有iOS项目时遇“Could not build module 'React'”错误求助

Hey, I’ve run into this exact issue before when integrating React Native into an existing iOS project—super frustrating, but there are a few common fixes that usually get things back on track. Let’s break down the most likely causes and solutions:

• Double-check your React Native setup & linking
  First, confirm you’ve installed all dependencies properly with npm install or yarn install. For RN versions 0.60+, auto-linking should handle most framework connections, but it’s easy to miss a step:

  • Always open your project’s .xcworkspace file (not .xcodeproj) in Xcode—CocoaPods manages RN dependencies now, so the regular project file won’t include them.
  • Head to Build Phases > Link Binary With Libraries in your target settings. Make sure libReact.a or core RN modules like React-Core and React-RCTText are listed. If not, run pod install again from your project’s ios directory.

• Fix your Header Search Paths
  This is the #1 culprit for this error. Xcode can’t locate React’s header files if the paths are misconfigured:

  • In Xcode, go to your target’s Build Settings > Search Paths > Header Search Paths.
  • Add these paths and set them to recursive:

    $(SRCROOT)/../node_modules/react-native/React
    $(SRCROOT)/../node_modules/react-native/Libraries
    

  • Also, make sure $(inherited) is at the top of the list—this lets Xcode pick up paths defined by CocoaPods.

• Clear cached build data
  Stale build files often cause random module errors. Try these steps:

  • Go to Product > Clean Build Folder (shortcut: Cmd+Shift+K) in Xcode.
  • Delete Derived Data: Open Xcode > Settings > Locations > Derived Data, click the arrow to open the folder, and delete everything inside.
  • Restart Xcode and try building again.

• Validate your CocoaPods setup
  Outdated pods or a misconfigured Podfile can break module imports:

  • Make sure your CocoaPods version is compatible with your React Native version (check the RN docs for recommended versions).
  • Open your ios/Podfile and confirm it includes the core RN pod setup. A basic working configuration looks like this:

    require_relative '../node_modules/react-native/scripts/react_native_pods'
    require_relative '../node_modules/@react-native-community/cli-platform-ios/native_modules'
    
    platform :ios, '13.0'
    
    target 'YourExistingAppName' do
      config = use_native_modules!
    
      use_react_native!(
        :path => config[:reactNativePath]
        # Uncomment below to enable Hermes
        # :hermes_enabled => true
      )
    
      # Add your existing app's pods here
    end
    

  • After updating the Podfile, run pod deintegrate then pod install to reset your pods completely.

• Check your active scheme
  Sometimes selecting the wrong scheme in Xcode causes module issues. Make sure you’ve selected your main app target’s scheme, not a React Native test or helper scheme.

If none of these fix the problem, sharing your React Native version, Xcode version, and a snippet of your Podfile would help narrow down the exact issue.

内容的提问来源于stack exchange，提问作者Kishoretheju