Dev Note

Capacitor 플러그인을 return 하면 await 가 멈추는 이유 — thenable 함정

Hangul Lab 은 외국인 성인이 한글을 배우는 앱입니다. 웹으로 만든 화면을 Capacitor 로 감싸 Android 와 iOS 에 내놓고, iOS 의 Pro 구독 결제는 RevenueCat SDK(@revenuecat/purchases-capacitor)에 맡깁니다.

그 iOS 빌드에서 'Try Pro' 버튼을 눌러도 아무 일도 일어나지 않는다는 보고를 받았습니다. 결제창도, 오류 문구도, 크래시도 없었습니다. 원인은 결제 초기화 함수 마지막 줄의 return Purchases 였습니다. 이 한 줄이 왜 await 를 영원히 멈추게 하는지 기록해 둡니다. 버전은 @capacitor/core 8.5.0, @revenuecat/purchases-capacitor 13.5.0 기준입니다.

증상: 가격이 빠진 버튼

보고에 딸린 화면에서 먼저 눈에 띈 건 버튼 문구였습니다. 업셀 버튼은 상품 정보를 받으면 Try Pro — (가격), 못 받으면 Try Pro 로 그립니다. 앱 시작 때의 상품 조회가 끝나지 않았다는 뜻입니다.

눌러도 반응이 없는 이유는 당시 버튼 핸들러에 그대로 있었습니다.

// 당시 useEntitlement.js 의 버튼 핸들러
const subscribe = useCallback(async () => {
  if (state.billingReady) {
    const r = await purchase();
    // ...
    return;
  }
  // 여기 오면 스토어 결제를 못 쓰는 상태다(웹 개발 환경 등).
  if (!BETA_GRANT) return;             // <- 상품을 못 받았으면 조용히 끝난다
  // ...
}, []);

상품 조회가 끝나지 않으면 billingReady 가 false 로 남고, 버튼은 개발용 분기로 빠져 조용히 돌아갑니다. 그러니 진짜 질문은 상품 조회가 왜 끝나지 않는가였습니다.

같은 빌드를 iPad 시뮬레이터에 올리자 똑같이 재현됐습니다.

처음 의심한 것들, 그리고 아니었던 이유

1. 스토어·RevenueCat 설정

RevenueCat 의 오퍼링과 상품 연결, App Store Connect 의 구독 상품 상태, 유료 앱 계약, 번들 ID, 인앱 결제 키, 웹 번들에 들어간 RevenueCat 공개 키까지 전부 정상이었습니다. RevenueCat 쪽에는 문제가 난 기기의 익명 고객 레코드도 생겨 있었습니다. SDK 가 configure 까지는 했다는 뜻입니다.

2. 새 OS 의 StoreKit 샌드박스

새 iOS 직후 시뮬레이터에서 오퍼링이 안 내려오던 사례가 실제로 있어서(RevenueCat purchases-ios #4954, iOS 18.4), 시뮬레이터의 통합 로그를 직접 받아 봤습니다.

xcrun simctl spawn <UDID> log stream --style compact --predicate 'process == "App"'

StoreKit 로그에는 상품 요청 뒤 Parsing 1 products in response 가 찍혀 있었습니다. 상품이 정상으로 왔습니다. 함께 보인 ASDErrorDomain Code=509 "No active account" 는 샌드박스 계정이 없는 시뮬레이터에서 거래 내역 조회가 실패한 것이라 상품 조회와는 무관했습니다. 그리고 이 상품 요청은 JS 가 아무것도 묻기 전, configure 직후에 네이티브 SDK 가 스스로 보낸 것이었습니다. 스토어도 SDK 도 살아 있었습니다.

3. 브리지 콜백 ID -1

Capacitor 는 JS 에서 네이티브로 넘어가는 호출을 Xcode 콘솔에 남깁니다.

⚡️  To Native ->  App addListener 34321175
⚡️  To Native ->  Purchases setLogLevel -1
⚡️  To Native ->  Purchases configure -1

끝의 숫자는 콜백 ID 입니다. RevenueCat 호출만 -1 이라 "응답 콜백이 없어서 await configure() 가 안 끝난다"고 의심했는데, 틀렸습니다. 플러그인의 Swift 소스에서 configure 는 응답 없는 호출(CAPPluginReturnNone)이고, 브리지는 콜백이 없는 호출에 원래 '-1' 을 붙입니다. 이런 호출은 보내는 즉시 끝나므로 await 도 바로 풀립니다.

대신 같은 로그에 진짜 단서가 있었습니다. configure 다음에 와야 할 getOfferings 호출이 한 번도 네이티브로 넘어오지 않았습니다. 네이티브는 멀쩡한데 JS 가 다음 질문을 하지 않고 있었던 겁니다.

진단: 체크포인트를 화면에 그리기

JS 가 어느 await 에서 멈추는지 보려 했지만, xcrun simctl launch --console-pty 로 받은 앱 출력은 브리지 로그 몇 줄 뒤로 끊겼고 console.log 는 한 줄도 보이지 않았습니다. 로그 경로와 씨름하는 대신, 단계마다 체크포인트를 배열에 쌓아 화면에 그리기로 했습니다. 진단 빌드에서만 켜지게 빌드 변수로 막았습니다.

// 진단용 체크포인트 (당시 코드를 줄인 것). VITE_RC_DEBUG=1 빌드에서만 쌓인다.
const TRACE = [];
export const getTrace = () => TRACE.join(' > ');
const trace = (s) => { if (import.meta.env.VITE_RC_DEBUG === '1') TRACE.push(s); };

async function rc() {
  trace('rc');
  const { Purchases } = await import('@revenuecat/purchases-capacitor');
  trace('import-ok');
  if (!rcInit) {
    rcInit = (async () => {
      // (setLogLevel 단계도 같은 식으로 찍었다)
      trace('configure');
      const r = await Purchases.configure({ apiKey: IOS_KEY });
      trace('configure-ok:' + String(r));
    })();
  }
  await rcInit;
  trace('rcInit-ok');
  return Purchases;
}

// 호출하는 쪽: const Purchases = await rc(); trace('getOfferings'); ...
// 화면 쪽: 1초마다 getTrace() 를 읽어 <p>trace: {trace}</p> 로 그린다.

시뮬레이터 화면에 찍힌 결과는 이랬습니다.

debug: ready=false price=null reason=null
trace: rc > rc > rc > import-ok > setLogLevel > import-ok > import-ok >
       setLogLevel-ok:-1 > configure > configure-ok:-1 >
       rcInit-ok > rcInit-ok > rcInit-ok

앱 시작 때 상품 조회, 구독 복원, 리스너 등록이 동시에 rc() 를 불러 rc 가 세 번 찍혔고, 셋 다 await rcInit 를 통과했습니다(rcInit-ok 세 번). 그런데 호출한 쪽에서 찍혀야 할 getOfferings 는 하나도 없습니다. reason=null 은 상품 조회가 성공도 실패도 하지 않았다는 뜻입니다. try/catch 의 catch 에도 걸린 게 없었습니다.

rcInit-ok 와 호출한 쪽의 다음 줄 사이에 있는 코드는 단 한 줄입니다.

// 당시 billing.js (iOS 경로)
let rcInit = null;
async function rc() {
  const { Purchases } = await import('@revenuecat/purchases-capacitor');
  if (!rcInit) rcInit = Purchases.configure({ apiKey: IOS_KEY });
  await rcInit;
  return Purchases;                    // <- 이 한 줄
}

export async function getSubscription() {
  // ...
  try {
    const Purchases = await rc();      // <- 여기서 영원히 멈춘다
    const pkg = await monthlyPackage(Purchases);
    if (!pkg) return { available: false, reason: 'no-offering' };
    return { available: true, price: pkg.product?.priceString || null };
  } catch (e) {
    return { available: false, reason: String(e?.message || e) };
  }
}

초기화가 끝난 객체를 돌려줄 뿐인데, 돌려받는 쪽의 await rc() 가 끝나지 않습니다.

원인: 모든 질문에 "예"라고 답하는 객체

Capacitor 플러그인은 Proxy 다

registerPlugin() 이 돌려주는 플러그인 객체는 메서드가 미리 정의된 평범한 객체가 아닙니다.

// @capacitor/core 8.5.0 — registerPlugin() 안쪽
const proxy = new Proxy({}, {
  get(_, prop) {
    switch (prop) {
      // https://github.com/facebook/react/issues/20030
      case '$$typeof':
        return undefined;
      case 'toJSON':
        return () => ({});
      case 'addListener':
        return pluginHeader ? addListenerNative : addListener;
      case 'removeListener':
        return removeListener;
      default:
        return createPluginMethodWrapper(prop);   // 그 밖의 이름은 전부 함수
    }
  },
});

몇 가지 예외를 빼면 어떤 이름을 물어도 그 이름의 메서드 래퍼를 돌려줍니다. 네이티브 메서드 목록을 JS 가 미리 알 필요가 없게 하려는 설계입니다. 그래서 존재하지 않는 Purchases.then 도 함수입니다. RevenueCat 이 내보내는 Purchases 는 이 Proxy 를 한 번 더 Proxy 로 감쌌지만, 메서드 하나만 가로채고 나머지는 그대로 넘기므로 결과는 같습니다.

$$typeof 를 막아 둔 줄의 링크(facebook/react#20030)가 힌트입니다. React 가 묻는 속성에 플러그인이 함수로 답해서 생긴 문제를 막은 것입니다. 같은 일이 then 에서도 일어나는데, 이번에 묻는 쪽은 언어 자체입니다.

async 함수의 return 은 resolve 를 거친다

async 함수가 return 한 값은 곧바로 결과가 되지 않고, 함수가 돌려준 프로미스의 resolve 함수에 넘겨집니다(ECMAScript 명세의 AsyncBlockStart). resolve 함수는 값을 이렇게 처리합니다(CreateResolvingFunctions 의 resolve 단계).

  1. 값이 객체가 아니면 그 값으로 이행(fulfill)하고 끝낸다.
  2. 객체면 then 속성을 읽는다.
  3. then 이 호출 가능하지 않으면 그 객체로 이행하고 끝낸다.
  4. 호출 가능하면 작업(NewPromiseResolveThenableJob)을 마이크로태스크로 예약하고, 거기서 then 을 이 프로미스의 resolve·reject 를 인자로 해서 부른다. 이제 프로미스의 운명은 그 then 이 둘 중 하나를 불러 주는 데 달렸다.

Promises/A+ 명세가 "Promise Resolution Procedure"(2.3절)라고 부르는 절차입니다. 다른 구현의 프로미스와 섞어 쓸 수 있도록 언어는 then 메서드가 있는지만 보고 상대를 프로미스처럼 다룹니다(MDN 의 Thenable). 그리고 이 절차 어디에도 타임아웃은 없습니다. then 이 두 콜백 중 어느 것도 부르지 않으면 프로미스는 영원히 대기합니다.

await x 도 먼저 PromiseResolve(%Promise%, x) 로 x 를 프로미스로 바꾸는데, x 가 진짜 프로미스가 아니면 새 프로미스를 만들어 같은 resolve 절차에 넘깁니다. 그래서 await Purchases 나 Promise.resolve(Purchases) 도 결과가 같습니다.

Capacitor 의 then 래퍼는 resolve 를 부르지 않는다

그러면 Purchases.then(resolve, reject) 는 무엇을 할까요. Proxy 가 돌려주는 래퍼는 이렇습니다.

// @capacitor/core 8.5.0 — createPluginMethodWrapper (일부 생략, 주석은 덧붙인 것)
const wrapper = (...args) => {            // then(resolve, reject) 이면 args = [resolve, reject]
  const p = loadPluginImplementation().then((impl) => {
    const fn = createPluginMethod(impl, prop);   // 네이티브 메서드 목록에서 'then' 을 찾는다
    if (fn) {
      return fn(...args);
    } else {
      throw new CapacitorException(
        `"${pluginName}.${prop}()" is not implemented on ${platform}`,
        ExceptionCode.Unimplemented);
    }
  });
  return p;                               // 이 프로미스가 거부될 뿐, resolve/reject 는 안 불린다
};
  1. 래퍼는 resolve 와 reject 를 "네이티브에 넘길 인자"로 받아 둘 뿐, 어느 쪽도 부르지 않습니다.
  2. 네이티브가 등록한 메서드 목록에서 then 을 찾습니다. 당연히 없고, iOS 용 JS 구현도 없으니 메서드를 만들지 못합니다.
  3. "Purchases.then()" is not implemented on ios 예외가 납니다. 그런데 이 예외는 래퍼가 돌려준 별개의 프로미스 안에서, 비동기로 납니다.

NewPromiseResolveThenableJob 은 then 호출이 동기적으로 예외를 던질 때만 reject 를 대신 불러 주고, then 의 반환값은 보지 않습니다. 결국 원래 프로미스는 resolve 도 reject 도 받지 못한 채 대기하고, 에러는 아무도 구독하지 않는 프로미스에 실려 처리되지 않은 거부(unhandled rejection)가 됩니다. 이 호출은 브리지를 건너기 전에 JS 안에서 거부되므로 네이티브 로그에도 then 은 나오지 않습니다. 로그가 configure 에서 끊겨 있던 이유입니다.

동기냐 비동기냐가 갈랐다

이 차이를 확인하려고 Capacitor 의 Proxy 를 흉내 낸 객체로 Node 22 에서 실험했습니다.

// 예시: Capacitor 플러그인 Proxy 를 흉내 낸 최소 재현 (Node 22)
function fakePlugin(name, syncThrow = false) {
  return new Proxy({}, {
    get(_, prop) {
      if (prop === '$$typeof') return undefined;
      if (prop === 'toJSON') return () => ({});
      return (...args) => {
        const err = new Error(`"${name}.${String(prop)}()" is not implemented on ios`);
        if (syncThrow) throw err;                         // 동기로 던지면
        return Promise.resolve().then(() => { throw err; }); // 비동기로 거부하면 (Capacitor 와 같은 모양)
      };
    },
  });
}

// 브라우저처럼 처리되지 않은 거부가 프로세스를 끝내지 않게 한다
process.on('unhandledRejection', (e) => console.log('unhandledRejection:', e.message));

async function getPlugin() { return fakePlugin('Purchases', process.argv[2] === 'sync'); }

try {
  console.log('before');
  const p = await getPlugin();
  console.log('after');
} catch (e) {
  console.log('caught:', e.message);
}

// $ node repro.mjs sync
//   before
//   caught: "Purchases.then()" is not implemented on ios
// $ node repro.mjs async
//   before
//   unhandledRejection: "Purchases.then()" is not implemented on ios
//   (after 도 caught 도 찍히지 않고, Node 가 끝나지 않은 최상위 await 를 경고한다)

래퍼가 예외를 바로 던지면 catch 에 잡히고, 비동기로 거부하면 before 만 찍히고 끝납니다. Node 는 이를 경고로 알려 주지만 앱의 WebView 에서는 반응 없는 버튼으로 보일 뿐입니다.

같은 가짜 플러그인으로 흔한 모양들이 0.5초 안에 끝나는지 본 결과입니다.

코드 모양결과
await P멈춤
async () => P 의 결과를 await멈춤
Promise.resolve(P)멈춤
Promise.all([P])멈춤
.then(() => P)멈춤
async () => ({ plugin: P })정상
모듈 변수에 담고 아무것도 반환하지 않음정상

const { Purchases } = await import(...) 는 안전합니다. await 대상이 then 을 내보내지 않는 모듈 네임스페이스 객체이기 때문입니다.

고친 방법

원칙은 하나입니다. 플러그인 객체를 프로미스의 결과값 자리에 두지 않는다. 초기화 함수는 아무것도 반환하지 않고, 플러그인 객체는 모듈 변수에만 담습니다.

// 고친 billing.js — 플러그인 객체는 모듈 변수에만 담고, 어떤 async 함수도 그것을 반환하지 않는다.
let RC = null;
let rcInit = null;
async function ensureRC() {
  if (!rcInit) {
    rcInit = (async () => {
      const { Purchases, LOG_LEVEL } = await import('@revenuecat/purchases-capacitor');
      // 진단 빌드에서만 SDK 로그를 푼다.
      if (import.meta.env.VITE_RC_DEBUG === '1') await Purchases.setLogLevel({ level: LOG_LEVEL.VERBOSE });
      await Purchases.configure({ apiKey: IOS_KEY });
      RC = Purchases;
    })().catch((e) => {
      rcInit = null;                 // 다음 시도에서 다시 초기화할 수 있게
      throw e;
    });
  }
  await rcInit;                      // 반환값 없음
}

async function monthlyPackage() {
  const { current } = await RC.getOfferings();
  const pkgs = current?.availablePackages || [];
  return pkgs.find((p) => p.identifier === '$rc_monthly') || pkgs[0] || null;
}

export async function getSubscription() {
  // ...
  try {
    await ensureRC();
    const pkg = await monthlyPackage();
    // ...
  } catch (e) { /* ... */ }
}

초기화 약속은 하나만 두어 동시에 불려도 configure 가 한 번만 돌고, 실패하면 비워서 다시 시도합니다. Android 쪽 자체 결제 플러그인(Billing)도 같은 Proxy 라 같은 규칙을 적용했습니다.

함께 고친 것: 조용한 버튼

사용자 입장에서 더 나빴던 건 "아무 일도 일어나지 않는다"는 점이라 버튼 쪽도 손봤습니다.

  • 스토어와 통신하는 동안 버튼을 잠그고 Connecting… 으로 바꿉니다.
  • 상품 조회를 0초·4초·15초에 시도하고 버튼을 누르는 순간에도 한 번 더 봅니다. 그래도 없으면 연결을 확인해 달라는 문구를, 구매가 실패하면 실패 문구를 띄웁니다. 사용자가 결제 시트를 직접 닫은 경우만 조용히 넘어갑니다.
  • 앱을 켤 때마다 부르던 restorePurchases() 를 getCustomerInfo() 로 바꾸고 '구매 복원' 버튼을 따로 달았습니다. RevenueCat 문서는 restorePurchases 가 OS 로그인 창을 띄울 수 있으니 사용자 동작으로만 부르라고 안내합니다.
// 유료 화면 세 곳이 같이 쓰는 구독 버튼
export default function UpsellCta() {
  const { price, subscribe, restorePurchases, busy, notice } = useEntitlement();
  return (
    <>
      <button className="upsell-cta" disabled={busy} onClick={subscribe}>
        {busy ? 'Connecting…' : price ? `Try Pro — ${price}` : 'Try Pro'}
      </button>
      {notice && <p className="upsell-notice" role="status">{notice}</p>}
      <p className="upsell-note">
        Cancel any time in your app store.{' '}
        <button className="upsell-restore" disabled={busy} onClick={restorePurchases}>Restore purchases</button>
      </p>
    </>
  );
}

검증

같은 시뮬레이터에서 버튼에 가격이 붙어 Try Pro — (가격) 으로 그려졌고, 누르면 StoreKit 결제 흐름이 시작돼 Apple 계정 로그인 창이 떴습니다(샌드박스 계정이 없는 시뮬레이터라 여기까지가 정상). 창을 닫으면 버튼이 원래대로 돌아왔고, 회화 탭의 업셀 버튼도 같았습니다. 체크포인트 코드는 정식 빌드에서 걷어내고 SDK 상세 로그만 빌드 변수로 켤 수 있게 남겼습니다.

Capacitor 쪽은 아직 그대로다

같은 문제가 Capacitor 저장소에 이슈로 올라가 있고(ionic-team/capacitor#8469), then 에 undefined 를 돌려주게 하는 수정 PR 도 두 개(#8473, #8582) 있습니다. 다만 2026년 11월 확인 시점에 셋 다 열린 상태였고 main 브랜치의 Proxy 도 위 코드와 같았습니다. 버전을 올린다고 사라지는 문제가 아직 아니므로 앱 코드에서 피해야 합니다.

재발 방지 체크리스트

코드 규칙

  • 플러그인 객체를 async 함수에서 return 하지 않는다. await, Promise.resolve(), Promise.all(), .then() 콜백의 반환값도 같은 자리입니다. 값을 프로미스로 감싸 돌려주는 지연 로딩·싱글턴 헬퍼가 특히 위험합니다.
  • 꼭 넘겨야 하면 평범한 객체로 감싼다. resolve 절차가 then 을 묻는 대상은 바깥 객체이고, 거기엔 then 이 없습니다.
  • Proxy 로 감쌀 거라면 then 을 명시적으로 막는다. 그대로 통과시키는 래퍼는 소용없습니다.
  • 타입 검사기는 잡아 주지 않는다. 인터페이스에 then 이 없으니 TypeScript 에게 Promise<PurchasesPlugin> 은 멀쩡한 타입입니다. 문제는 런타임 Proxy 에 있습니다.
// 예시 1: 꼭 반환해야 한다면 평범한 객체로 감싼다
async function loadPurchases() {
  const { Purchases } = await import('@revenuecat/purchases-capacitor');
  await Purchases.configure({ apiKey: IOS_KEY });
  return { plugin: Purchases };      // resolve 절차가 then 을 묻는 대상은 바깥 객체다
}
const { plugin } = await loadPurchases();

// 예시 2: Proxy 로 한 번 더 감쌀 거라면 then 을 명시적으로 막는다
const nonThenable = (plugin) =>
  new Proxy(plugin, {
    get: (target, prop, receiver) =>
      prop === 'then' ? undefined : Reflect.get(target, prop, receiver),
  });

진단할 때 볼 지문

  • 네이티브 브리지 로그에 초기화 호출까지만 있고 그다음 호출이 넘어오지 않는다. try/catch 에도 아무것도 안 걸린다.
  • 처리되지 않은 거부에 "플러그인이름.then()" is not implemented 가 있다. 디버그 빌드에서 unhandledrejection 이벤트를 화면에 내보내 두면 바로 보입니다.
  • WebView 의 console.log 가 잘 잡히지 않으면 단계별 체크포인트를 화면에 그리는 편이 빠릅니다.

UI 규칙

  • 결제 버튼은 누르면 반드시 무언가를 보여 줘야 합니다. 진행 중 상태가 있었다면 이 버그는 "반응 없음"이 아니라 "계속 연결 중"으로 보였을 겁니다.
  • 스토어 호출에 타임아웃을 걸면 무한 대기를 오류로 바꿀 수 있습니다. 명세에 대기의 끝이 없으니 끝은 앱이 정해야 합니다.

남는 교훈

모든 속성에 답하는 객체는 덕 타이핑과 상극이다. 프로미스 절차는 then 을, JSON.stringify 는 toJSON 을, React 는 $$typeof 를 묻습니다. Capacitor 는 뒤의 둘만 막아 두었습니다. Proxy 기반 객체를 다룬다면 그 객체가 어디까지 흘러가는지 따져 봐야 합니다.

"끝나지 않음"은 "실패"보다 찾기 어렵다. 실패는 스택 트레이스를 남기지만 끝나지 않는 await 는 아무것도 남기지 않습니다. 이번에 답을 준 것도 에러 메시지가 아니라 "어디까지 왔는가"를 순서대로 찍은 기록이었습니다.

Hangul Lab — 외국인을 위한 한글 학습 앱입니다. 자모와 받침, 음절 소리부터 생활 회화까지 단계별로 익힙니다. Google Play에서 받기
← 블로그 목록으로