集成Stripe时触发document.querySelectorAll is not a function报错如何解决

报错原因 #

该错误由服务端环境缺少浏览器DOM API导致。@stripe/stripe-js的loadStripe方法内部会调用document.querySelectorAll查找已注入的Stripe脚本，而你当前的代码在组件顶层直接执行了loadStripe，在Next.js等支持服务端渲染的框架中，这部分代码会先在服务端运行，Node环境不存在document对象，因此抛出对应报错。

修复方案 #

根据你使用的Next.js路由模式选择对应方案即可：

方案1：App Router（Next.js 13+） #

给组件添加客户端标记，并将loadStripe初始化逻辑放到客户端挂载后执行：

'use client'

import { useRef, useState, useEffect } from 'react'
import { Elements } from "@stripe/react-stripe-js"
import { loadStripe } from "@stripe/stripe-js"
import PaymentForm from './PaymentForm' // 替换为你的PaymentForm实际导入路径

const PUBLIC_KEY = process.env.NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY

export default function StripePaymentWrapper({ helpRequest, callback }) {
  const paymentRef = useRef(null)
  const [stripePromise, setStripePromise] = useState(null)

  // 仅客户端挂载后初始化Stripe
  useEffect(() => {
    setStripePromise(loadStripe(PUBLIC_KEY))
  }, [])

  // 初始化完成前展示加载状态
  if (!stripePromise) return <div>支付组件加载中...</div>

  return (
    <Elements stripe={stripePromise}>
      <PaymentForm ref={paymentRef} helpRequest={helpRequest} callback={callback} />
    </Elements>
  )
}

方案2：Pages Router（Next.js 12及更早版本） #

通过next/dynamic关闭Stripe相关组件的服务端渲染：

1. 新建单独的Stripe支付包装组件components/StripePayment.js：

import { useRef } from 'react'
import { Elements } from "@stripe/react-stripe-js"
import { loadStripe } from "@stripe/stripe-js"
import PaymentForm from './PaymentForm'

const PUBLIC_KEY = process.env.NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY
const stripeTestPromise = loadStripe(PUBLIC_KEY)

export default function StripePayment({ helpRequest, callback }) {
  const paymentRef = useRef(null)
  return (
    <Elements stripe={stripeTestPromise}>
      <PaymentForm ref={paymentRef} helpRequest={helpRequest} callback={callback} />
    </Elements>
  )
}

2. 在父组件中动态导入该组件，关闭SSR：

import dynamic from 'next/dynamic'

// 动态导入时关闭服务端渲染
const StripePayment = dynamic(() => import('@/components/StripePayment'), {
  ssr: false,
  loading: () => <div>支付组件加载中...</div>
})

// 父组件内直接使用即可
export default function ParentPage() {
  // 你的业务逻辑
  return <StripePayment helpRequest={helpRequest} callback={callback} />
}

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