使用react-stripe-js遇IntegrationError：无法存在多个Embedded Checkout对象

问题根源 #

触发IntegrationError: You cannot have multiple Embedded Checkout objects错误，核心原因是多次渲染<EmbeddedCheckout>组件时，旧的Checkout实例未被正确销毁，导致页面同时存在多个实例引发冲突。更换EmbeddedCheckoutProvider的key无法解决问题，因为key变化仅会触发组件重新渲染，但Stripe底层的Checkout实例并未被清理。

可行解决方案 #

1. 严格控制组件渲染时机 #

只在需要显示结账表单时才渲染<EmbeddedCheckoutProvider>和<EmbeddedCheckout>，通过状态判断避免不必要的重复渲染：

import { useState } from 'react';
import { EmbeddedCheckoutProvider, EmbeddedCheckout } from '@stripe/react-stripe-js';

function CheckoutComponent({ stripePromise, shouldShowCheckout }) {
  // 仅当需要显示结账表单时才渲染组件
  if (!shouldShowCheckout) {
    return null;
  }

  return (
    <div id="checkout">
      <EmbeddedCheckoutProvider stripe={stripePromise}>
        <EmbeddedCheckout />
      </EmbeddedCheckoutProvider>
    </div>
  );
}

当不需要结账功能时，将shouldShowCheckout设为false，组件卸载时会自动清理Stripe的Checkout实例。

2. 手动销毁Checkout实例（底层API方式） #

如果必须保持组件挂载状态，可以通过Stripe底层API手动销毁旧实例。利用useStripe钩子获取Stripe实例，在组件卸载时调用销毁方法：

import { useState, useEffect } from 'react';
import { EmbeddedCheckoutProvider, EmbeddedCheckout, useStripe } from '@stripe/react-stripe-js';

function CheckoutInner() {
  const stripe = useStripe();
  let checkoutInstance = null;

  useEffect(() => {
    const initCheckout = async () => {
      if (stripe) {
        checkoutInstance = await stripe.initEmbeddedCheckout({
          clientSecret: '你的支付会话client_secret'
        });
      }
    };

    initCheckout();

    // 组件卸载时销毁Checkout实例
    return () => {
      if (checkoutInstance) {
        checkoutInstance.destroy();
      }
    };
  }, [stripe]);

  return <EmbeddedCheckout />;
}

function CheckoutComponent({ stripePromise }) {
  return (
    <div id="checkout">
      <EmbeddedCheckoutProvider stripe={stripePromise}>
        <CheckoutInner />
      </EmbeddedCheckoutProvider>
    </div>
  );
}

注意：每次初始化时要确保使用最新的clientSecret，避免复用过期密钥引发其他问题。

3. 全局仅保留一个EmbeddedCheckoutProvider实例 #

检查应用代码，确保全局范围内只存在一个<EmbeddedCheckoutProvider>，多个Provider实例会直接导致多Checkout对象冲突。

关键注意事项 #

• 避免在循环、重复渲染的逻辑中放置结账组件，确保页面同一时间只有一个Checkout实例。
• 组件卸载时React会自动清理Stripe相关资源，但要确保组件是真正被卸载（而非通过CSS隐藏）。

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