문제 해결

@boostbrothers/react-native-naver-map 사용 중 자주 발생하는 문제와 해결 방법을 정리합니다.

지도가 표시되지 않는 경우

클라이언트 ID 미설정

가장 흔한 원인입니다. 클라이언트 ID가 올바르게 설정되어 있는지 확인하세요.

iOS (Info.plist):

<key>NMFClientId</key>
<string>YOUR_ACTUAL_CLIENT_ID</string>

Android (AndroidManifest.xml):

<meta-data
    android:name="com.naver.maps.map.CLIENT_ID"
    android:value="YOUR_ACTUAL_CLIENT_ID" />

클라이언트 ID에 앞뒤 공백이 없는지 확인하세요. 복사 시 실수로 공백이 포함될 수 있습니다.

`style={{ flex: 1 }}`이 없는 경우

NaverMapView에 명시적인 크기를 지정해야 합니다.

// 잘못된 예
<NaverMapView />

// 올바른 예
<NaverMapView style={{ flex: 1 }} />
// 또는
<NaverMapView style={{ width: 300, height: 400 }} />

지도가 빈 화면으로 표시되는 경우

onInitialized 콜백을 추가하여 초기화가 완료되는지 확인하세요.

<NaverMapView
  style={{ flex: 1 }}
  onInitialized={() => console.log('초기화 성공')}
/>

초기화 콜백이 호출되지 않는다면 네이티브 빌드 설정을 확인하세요.

iOS 빌드 오류

pod install 실패

Podfile에 네이버 지도 저장소 소스가 추가되어 있는지 확인합니다.

source 'https://github.com/CocoaPods/Specs.git'
source 'https://navermaps.github.io/ios-map-sdk/SpecsB3.git'

이후 캐시를 초기화하고 재설치합니다.

cd ios
pod cache clean --all
pod install

Xcode 빌드 오류 - Bitcode

네이버 지도 iOS SDK는 Bitcode를 지원하지 않습니다. Xcode 빌드 설정에서 Bitcode를 비활성화하세요.

Build Settings → Enable Bitcode → No

iOS New Architecture 마커 커스텀 뷰 문제

iOS New Architecture 환경에서 커스텀 뷰 마커가 동작하지 않는다면 자식 뷰에 collapsable={false}를 추가하세요.

<NaverMapMarkerOverlay latitude={lat} longitude={lng} width={60} height={30}>
  <View collapsable={false} style={{ width: 60, height: 30 }}>
    <Text>텍스트</Text>
  </View>
</NaverMapMarkerOverlay>

Android 빌드 오류

Maven 저장소 설정 오류

android/build.gradle에 네이버 지도 Maven 저장소가 추가되어 있는지 확인합니다.

allprojects {
    repositories {
        google()
        mavenCentral()
        maven { url 'https://repository.map.naver.com/archive/maven' }
    }
}

Minimum SDK 버전 오류

android/build.gradle의 minSdkVersion이 21 이상인지 확인합니다.

android {
    defaultConfig {
        minSdkVersion 21
    }
}

Duplicate class 오류

네이버 지도 SDK와 다른 라이브러리 간 클래스 충돌이 발생하면 android/app/build.gradle에 다음을 추가합니다.

configurations.all {
    resolutionStrategy {
        force 'com.google.android.gms:play-services-basement:18.1.0'
    }
}

클러스터링 문제

클러스터 탭 이벤트가 발생하지 않는 경우

onTapClusterLeaf 콜백을 NaverMapView에 전달했는지 확인하세요.

<NaverMapView
  clusters={[{ markers }]}
  onTapClusterLeaf={({ markerIdentifier }) => {
    // 이 콜백이 없으면 리프 탭 이벤트가 작동하지 않습니다
    console.log(markerIdentifier);
  }}
/>

마커가 클러스터링되지 않는 경우

카메라의 현재 줌 레벨이 clusters[].minZoom과 maxZoom 범위 내에 있는지 확인하세요.

clusters={[{
  markers,
  minZoom: 0,   // 이 범위 밖이면 클러스터링 안 됨
  maxZoom: 16,
}]}

또한 마커들 사이의 거리가 screenDistance보다 멀면 클러스터링되지 않습니다.

카메라 애니메이션 문제

animateCameraTo가 동작하지 않는 경우

ref가 올바르게 설정되어 있는지, 그리고 지도 초기화 후에 호출하는지 확인하세요.

const mapRef = useRef<NaverMapViewRef>(null);

<NaverMapView
  ref={mapRef}
  onInitialized={() => {
    // 초기화 후에만 ref 메서드 호출 가능
    mapRef.current?.animateCameraTo({ latitude: 37.5, longitude: 126.9 });
  }}
/>

카메라 Props와 Ref 메서드 충돌

camera prop과 animateCameraTo ref 메서드를 동시에 사용하면 충돌이 발생할 수 있습니다.

선언형 제어: camera, region props 사용
명령형 제어: ref.animateCameraTo() 등 사용

둘 중 하나만 사용하는 것을 권장합니다.

Expo 관련 문제

Expo Go에서 동작하지 않는 경우

이 라이브러리는 네이티브 모듈을 포함하므로 Expo Go에서는 동작하지 않습니다. Expo Development Build를 사용하세요.

npx expo run:ios
# 또는
npx expo run:android

Config Plugin 오류

app.json에서 Config Plugin 설정을 확인하세요.

{
  "expo": {
    "plugins": [
      [
        "@boostbrothers/react-native-naver-map",
        { "client_id": "YOUR_CLIENT_ID" }
      ]
    ]
  }
}

설정 변경 후 반드시 prebuild를 실행하세요.

npx expo prebuild --clean

알려진 제한사항

커스텀 뷰 마커 캐싱 미지원: 커스텀 React 뷰로 만든 마커는 이미지 캐싱이 지원되지 않아 대량 마커에 적합하지 않습니다.
Android FPS 제한: fpsLimit prop은 초기화 시에만 적용되며, 이후 변경해도 동작하지 않습니다.
TextureView: isUseTextureViewAndroid prop도 초기화 시에만 적용됩니다.
라이트 모드: isLiteModeEnabled가 활성화되면 레이어 그룹, 실내지도, 야간 모드, 심벌 클릭 이벤트 등을 사용할 수 없습니다.
네트워크 이미지: httpUri 이미지는 HTTP 헤더 등 커스텀 옵션이 지원되지 않습니다.

문제 해결

@boostbrothers/react-native-naver-map 사용 중 자주 발생하는 문제와 해결 방법을 정리합니다.

지도가 표시되지 않는 경우

클라이언트 ID 미설정

가장 흔한 원인입니다. 클라이언트 ID가 올바르게 설정되어 있는지 확인하세요.

iOS (Info.plist):

<key>NMFClientId</key>
<string>YOUR_ACTUAL_CLIENT_ID</string>

Android (AndroidManifest.xml):

<meta-data
    android:name="com.naver.maps.map.CLIENT_ID"
    android:value="YOUR_ACTUAL_CLIENT_ID" />

클라이언트 ID에 앞뒤 공백이 없는지 확인하세요. 복사 시 실수로 공백이 포함될 수 있습니다.

`style={{ flex: 1 }}`이 없는 경우

NaverMapView에 명시적인 크기를 지정해야 합니다.

// 잘못된 예
<NaverMapView />

// 올바른 예
<NaverMapView style={{ flex: 1 }} />
// 또는
<NaverMapView style={{ width: 300, height: 400 }} />

지도가 빈 화면으로 표시되는 경우

onInitialized 콜백을 추가하여 초기화가 완료되는지 확인하세요.

<NaverMapView
  style={{ flex: 1 }}
  onInitialized={() => console.log('초기화 성공')}
/>

초기화 콜백이 호출되지 않는다면 네이티브 빌드 설정을 확인하세요.

iOS 빌드 오류

pod install 실패

Podfile에 네이버 지도 저장소 소스가 추가되어 있는지 확인합니다.

source 'https://github.com/CocoaPods/Specs.git'
source 'https://navermaps.github.io/ios-map-sdk/SpecsB3.git'

이후 캐시를 초기화하고 재설치합니다.

cd ios
pod cache clean --all
pod install

Xcode 빌드 오류 - Bitcode

네이버 지도 iOS SDK는 Bitcode를 지원하지 않습니다. Xcode 빌드 설정에서 Bitcode를 비활성화하세요.

Build Settings → Enable Bitcode → No

iOS New Architecture 마커 커스텀 뷰 문제

iOS New Architecture 환경에서 커스텀 뷰 마커가 동작하지 않는다면 자식 뷰에 collapsable={false}를 추가하세요.

<NaverMapMarkerOverlay latitude={lat} longitude={lng} width={60} height={30}>
  <View collapsable={false} style={{ width: 60, height: 30 }}>
    <Text>텍스트</Text>
  </View>
</NaverMapMarkerOverlay>

Android 빌드 오류

Maven 저장소 설정 오류

android/build.gradle에 네이버 지도 Maven 저장소가 추가되어 있는지 확인합니다.

allprojects {
    repositories {
        google()
        mavenCentral()
        maven { url 'https://repository.map.naver.com/archive/maven' }
    }
}

Minimum SDK 버전 오류

android/build.gradle의 minSdkVersion이 21 이상인지 확인합니다.

android {
    defaultConfig {
        minSdkVersion 21
    }
}

Duplicate class 오류

네이버 지도 SDK와 다른 라이브러리 간 클래스 충돌이 발생하면 android/app/build.gradle에 다음을 추가합니다.

configurations.all {
    resolutionStrategy {
        force 'com.google.android.gms:play-services-basement:18.1.0'
    }
}

클러스터링 문제

클러스터 탭 이벤트가 발생하지 않는 경우

onTapClusterLeaf 콜백을 NaverMapView에 전달했는지 확인하세요.

<NaverMapView
  clusters={[{ markers }]}
  onTapClusterLeaf={({ markerIdentifier }) => {
    // 이 콜백이 없으면 리프 탭 이벤트가 작동하지 않습니다
    console.log(markerIdentifier);
  }}
/>

마커가 클러스터링되지 않는 경우

카메라의 현재 줌 레벨이 clusters[].minZoom과 maxZoom 범위 내에 있는지 확인하세요.

clusters={[{
  markers,
  minZoom: 0,   // 이 범위 밖이면 클러스터링 안 됨
  maxZoom: 16,
}]}

또한 마커들 사이의 거리가 screenDistance보다 멀면 클러스터링되지 않습니다.

카메라 애니메이션 문제

animateCameraTo가 동작하지 않는 경우

ref가 올바르게 설정되어 있는지, 그리고 지도 초기화 후에 호출하는지 확인하세요.

const mapRef = useRef<NaverMapViewRef>(null);

<NaverMapView
  ref={mapRef}
  onInitialized={() => {
    // 초기화 후에만 ref 메서드 호출 가능
    mapRef.current?.animateCameraTo({ latitude: 37.5, longitude: 126.9 });
  }}
/>

카메라 Props와 Ref 메서드 충돌

camera prop과 animateCameraTo ref 메서드를 동시에 사용하면 충돌이 발생할 수 있습니다.

선언형 제어: camera, region props 사용
명령형 제어: ref.animateCameraTo() 등 사용

둘 중 하나만 사용하는 것을 권장합니다.

Expo 관련 문제

Expo Go에서 동작하지 않는 경우

이 라이브러리는 네이티브 모듈을 포함하므로 Expo Go에서는 동작하지 않습니다. Expo Development Build를 사용하세요.

npx expo run:ios
# 또는
npx expo run:android

Config Plugin 오류

app.json에서 Config Plugin 설정을 확인하세요.

{
  "expo": {
    "plugins": [
      [
        "@boostbrothers/react-native-naver-map",
        { "client_id": "YOUR_CLIENT_ID" }
      ]
    ]
  }
}

설정 변경 후 반드시 prebuild를 실행하세요.

npx expo prebuild --clean

알려진 제한사항

커스텀 뷰 마커 캐싱 미지원: 커스텀 React 뷰로 만든 마커는 이미지 캐싱이 지원되지 않아 대량 마커에 적합하지 않습니다.
Android FPS 제한: fpsLimit prop은 초기화 시에만 적용되며, 이후 변경해도 동작하지 않습니다.
TextureView: isUseTextureViewAndroid prop도 초기화 시에만 적용됩니다.
라이트 모드: isLiteModeEnabled가 활성화되면 레이어 그룹, 실내지도, 야간 모드, 심벌 클릭 이벤트 등을 사용할 수 없습니다.
네트워크 이미지: httpUri 이미지는 HTTP 헤더 등 커스텀 옵션이 지원되지 않습니다.

문제 해결

목차

문제 해결

목차