NextJS应用集成Stripe Elements（卡片组件）不显示问题排查

我正在开发NextJS应用，集成Stripe Web Elements（卡片组件）时发现组件无法显示，查看元素检查器显示为空。相同代码在我的另一个ReactJS应用中可正常运行，请问我哪里操作出错了？

相关代码如下：

AddStripeCreditCard组件：

import { Elements } from "@stripe/react-stripe-js";
import { loadStripe } from "@stripe/stripe-js";

async function loadStripePromise(){
    const stripePromise = await loadStripe('PUBLISHABLE_KEY');
    return stripePromise;
}

const AddStripeCreditCard: React.FC<AddStripeCreditCardProps> = ({
  show,
  close,
}) => {
  return (
    <CustomModal show={show} close={close} >
      <Elements stripe={loadStripePromise()}>
        <CardDetailsForm />
      </Elements>
    </CustomModal>
  );
};

CardDetailsForm组件：

import { useElements, useStripe } from '@stripe/react-stripe-js';
import {
    CardNumberElement,
    CardCvcElement,
    CardExpiryElement,
    CardElement
  } from "@stripe/react-stripe-js";
  
const CardDetailsForm = () => {
  
  return (
    <form onSubmit={handleSubmit}>
        
      <label>
        Card number
        <CardNumberElement
          options={options}
          id='cardNumber'
        />
      </label>
      <label>
        Expiration date
        <CardExpiryElement
          options={options}
        />
      </label>
      <label>
        CVC
        <CardCvcElement
          options={options}
        />
      </label>
      <button type="submit" disabled={!stripe}>
        Pay
      </button>
    </form>
  );
};

我也尝试过使用CardElement，但问题依旧。

1. 错误传递Stripe实例给Elements组件 #

loadStripePromise是异步函数，直接调用它会返回Promise对象，但Elements组件需要接收未执行的Promise（不要用await）或已解析的Stripe实例。你的代码用await直接返回实例，导致每次渲染都会创建新的Promise，Stripe无法正确初始化。

修复代码：

// 直接返回未执行的loadStripe Promise，不要用await
const stripePromise = loadStripe('PUBLISHABLE_KEY');

const AddStripeCreditCard: React.FC<AddStripeCreditCardProps> = ({
  show,
  close,
}) => {
  return (
    <CustomModal show={show} close={close} >
      <Elements stripe={stripePromise}>
        <CardDetailsForm />
      </Elements>
    </CustomModal>
  );
};

2. CardDetailsForm组件存在未定义变量 #

表单组件中handleSubmit、options、stripe三个变量都未定义，会导致组件渲染失败，Stripe元素无法正常挂载。

修复代码：

import { useElements, useStripe } from '@stripe/react-stripe-js';
import {
    CardNumberElement,
    CardCvcElement,
    CardExpiryElement,
    CardElement
  } from "@stripe/react-stripe-js";
  
const CardDetailsForm = () => {
  // 获取Stripe实例和Elements对象
  const stripe = useStripe();
  const elements = useElements();
  
  // 定义Stripe元素样式配置
  const options = {
    style: {
      base: {
        fontSize: '16px',
        color: '#424770',
        '::placeholder': {
          color: '#aab7c4',
        },
      },
      invalid: {
        color: '#9e2146',
      },
    },
  };

  // 实现表单提交处理函数
  const handleSubmit = async (e) => {
    e.preventDefault();
    if (!stripe || !elements) return;
    
    // 这里可以添加支付逻辑，比如创建PaymentIntent、验证卡片等
    const { error, paymentMethod } = await stripe.createPaymentMethod({
      type: 'card',
      card: elements.getElement(CardNumberElement),
    });
    // 后续处理错误或支付流程
  };
  
  return (
    <form onSubmit={handleSubmit}>
        
      <label>
        卡号
        <CardNumberElement
          options={options}
          id='cardNumber'
        />
      </label>
      <label>
        有效期
        <CardExpiryElement
          options={options}
        />
      </label>
      <label>
        CVC码
        <CardCvcElement
          options={options}
        />
      </label>
      <button type="submit" disabled={!stripe}>
        支付
      </button>
    </form>
  );
};

3. NextJS SSR环境限制 #

Stripe Web Elements需要在客户端浏览器环境中初始化，NextJS的服务端渲染（SSR）会导致脚本加载异常。

针对NextJS 13+ App Router #

给使用Stripe的组件添加'use client'指令，强制在客户端渲染：

'use client'; // 加在组件文件最顶部
import { Elements } from "@stripe/react-stripe-js";
import { loadStripe } from "@stripe/stripe-js";

// 后续代码...

针对NextJS Pages Router #

使用dynamic导入组件并禁用SSR：

import dynamic from 'next/dynamic';

// 动态导入组件，禁用服务端渲染
const AddStripeCreditCard = dynamic(() => import('./AddStripeCreditCard'), {
  ssr: false,
});

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