在 Gatsby 中使用 Stripe 处理支付从测试密钥到 Checkout 集成完整指南【免费下载链接】gatsbyReact-based framework with performance, scalability, and security built in.项目地址: https://gitcode.com/gh_mirrors/ga/gatsby本指南讲解如何基于 Gatsby 静态站点接入 Stripe 支付平台覆盖从注册账户、获取测试密钥到编写一键购买按钮、通过 gatsby-source-stripe 插件在构建期导入商品与价格的全过程。读完本文你将掌握两种典型的 Stripe Checkout 客户端集成方案并能安全地管理可发布密钥与机密密钥。文中代码均取自本仓库的 ecommerce-tutorial-with-stripe 示例 与 Gatsby E-commerce Tutorial可直接复制运行。为什么选择 Stripe 与 GatsbyGatsby 非常适合构建电商网站静态站点天然具备安全性页面从 React 编译为静态文件后性能极快且托管成本低廉。无论是经营在线商店、为公益组织接收捐赠还是按用量计费都需要一个支付处理渠道。Stripe 正是这类场景的理想方案——它提供了高质量的开发者 API、直观的管理后台Dashboard以及与前端完全解耦的托管式 Checkout 页面。Stripe 与 Gatsby 配合的关键优势在于Stripe 的 客户端专用 Checkoutclient-only Checkout 不需要任何后端组件。你可以在 Stripe Dashboard 中配置商品、价格和订阅计划卖单一商品时把价格 ID 硬编码进站点即可卖多商品时使用 gatsby-source-stripe 插件 在构建期拉取全部价格若希望站点随商品变动自动更新还可以用 Stripe webhook 事件触发重新部署。前置准备Stripe 账户与 API 密钥注册 Stripe 账户访问 Stripe Dashboard 注册页面创建账户。注册时可以按需选择要使用的集成与服务比如只收款还是同时向卖家/服务商付款这些选择后续都可以更改Stripe 会根据你的选择推荐 Payments、Billing 等服务。注册完成后还需要用地址、银行信息等经营资料激活账户。获取 Stripe 测试密钥登录 Stripe Dashboard 后在 Developers 菜单下可以找到 API 密钥。在激活账户之前你只能使用测试 API 密钥。测试密钥密钥中带test字样允许你在不产生真实扣款的情况下完整测试支付集成。测试模式下你拥有两个标准密钥生产模式同样如此密钥类型用途安全等级Publishable key可发布密钥可包含在公开分享的前端代码中例如前端页面与公共仓库可公开Secret key机密密钥用于服务端请求、插件配置等绝对不能公开必须保密测试期间必须使用名称中带test的密钥生产代码则需要使用 live 密钥。机密密钥绝不能被分享或提交到任何公共仓库——任何人拿到它都可以读取或代你向 Stripe 账户发起请求查看收费/购买信息甚至给客户退款。搭建 Gatsby 项目创建项目并启动开发服务器在终端中执行以下命令创建新项目并进入目录gatsby new e-commerce-gatsby-tutorial cd e-commerce-gatsby-tutorial运行gatsby develop启动开发服务器浏览器打开http://localhost:8000/即可看到默认首页之后对代码的修改会热重载。若需要查询验证数据可在开发模式下访问 GraphiQLhttp://localhost:8000/___graphql。安装 stripe/stripe-js 并加载 Stripe.jsStripe.js 库因 PCI 合规要求必须从 Stripe 服务器加载不能本地打包。Stripe 提供了 ES 模块形式的加载包装器stripe/stripe-js你可以像普通 npm 包一样导入npm install stripe/stripe-js最佳实践是延迟实例化直到用户点击结算按钮时才真正加载 Stripe.js从而提升首屏性能。同时为充分利用 Stripe 的高级反欺诈功能建议让 Stripe.js 覆盖用户结算旅程的每个页面而不只是结算页这样 Stripe 能检测到异常行为。启用 Checkout 客户端集成本教程使用 Stripe Checkout 的 client-only 模式需要先在 Checkout 设置中启用 Checkout client-only integration启用该选项会同步改变 Stripe 管理商品的界面若你之前用过商品管理工具请注意从未用过则无需担心。另外还需在账户设置中为 Stripe 账户命名更多配置细节可参考 Stripe 官方 Checkout 配置文档。示例一单个商品的一键购买按钮适合销售单个商品如电子书的场景一个按钮直接重定向到 Stripe 托管结算页。在 Stripe Dashboard 创建商品与价格通过 Stripe Dashboard 或 Stripe API 创建商品与价格。这是 Stripe 校验前端请求是否合法、并按所选商品/价格正确扣款的前提。注意测试与生产商品需要分别创建本地开发时务必先切换到 Viewing test data 再创建商品。编写 Checkout 组件在src/components/checkout.js中创建结算组件把YOUR STRIPE PUBLISHABLE KEY换成你自己的可发布密钥把lineItems中的price换成你从 Dashboard 拿到的价格 ID示例仓库的完整实现见 checkout.js// src/components/checkout.js import React, { useState } from react import { loadStripe } from stripe/stripe-js const buttonStyles { fontSize: 13px, textAlign: center, color: #000, padding: 12px 60px, boxShadow: 2px 5px 10px rgba(0,0,0,.1), backgroundColor: rgb(255, 178, 56), borderRadius: 6px, letterSpacing: 1.5px, } const buttonDisabledStyles { opacity: 0.5, cursor: not-allowed, } let stripePromise const getStripe () { if (!stripePromise) { stripePromise loadStripe(YOUR STRIPE PUBLISHABLE KEY) } return stripePromise } const Checkout () { const [loading, setLoading] useState(false) const redirectToCheckout async event { event.preventDefault() setLoading(true) const stripe await getStripe() const { error } await stripe.redirectToCheckout({ mode: payment, lineItems: [{ price: price_xxx, quantity: 1 }], successUrl: http://localhost:8000/page-2/, cancelUrl: http://localhost:8000/, }) if (error) { console.warn(Error:, error) setLoading(false) } } return ( button disabled{loading} style{ loading ? { ...buttonStyles, ...buttonDisabledStyles } : buttonStyles } onClick{redirectToCheckout} BUY MY BOOK /button ) } export default Checkout如果你的 Stripe 账户较旧、仍使用 SKU 对象而非 Price也可在lineItems中直接提供 SKU IDlineItems: [{ price: sku_xxx, quantity: 1 }]。将组件挂载到首页编辑src/pages/index.js导入Checkout /并放在Layout内。刷新http://localhost:8000/即可看到醒目的 BUY MY BOOK 按钮。这段代码做了什么getStripe()返回一个 Promise它解析为 Stripe 实例loadStripe用可发布密钥标识你的 Stripe 平台校验结算请求与商品和安全设置是否匹配并在你的 Stripe 账户上处理支付。示例仓库将其封装在 stripejs.js以单例模式确保只实例化一次 Stripe。redirectToCheckout()校验结算请求成功则重定向到 Stripe 托管结算页失败则 resolve 出一个error对象。务必把successUrl和cancelUrl替换为你应用的合适地址。按钮通过loading状态在跳转过程中禁用避免用户重复点击。示例二通过 gatsby-source-stripe 插件导入商品与价格不再硬编码价格 ID而是在构建期用 gatsby-source-stripe 插件 拉取 Stripe 账户中的价格数据动态生成商品列表。完整实现可参考 ecommerce-tutorial-with-stripe 示例。安装并配置插件npm install gatsby-source-stripe在gatsby-config.js中配置插件示例仓库配置见 gatsby-config.js// gatsby-config.js require(dotenv).config({ path: .env.${process.env.NODE_ENV}, }) module.exports { siteMetadata: { title: Gatsby E-commerce Starter, }, plugins: [ gatsby-plugin-react-helmet, { resolve: gatsby-source-stripe, options: { objects: [Price], // 要拉取的 Stripe 对象类型 secretKey: process.env.STRIPE_SECRET_KEY, downloadFiles: false, }, }, ], }gatsby-source-stripe通过你的机密密钥在构建期获取价格数据。该密钥绝不能出现在前端代码或 GitHub 上因此必须通过环境变量注入并使用dotenv按NODE_ENV加载对应的.env.${process.env.NODE_ENV}文件。使用环境变量管理密钥在项目根目录创建.env.development字段可参考示例仓库的 .env.example# .env.development GATSBY_STRIPE_PUBLISHABLE_KEYpk_test_xxx GATSBY_BUTTON_PRICE_IDprice_xxx STRIPE_SECRET_KEYsk_test_xxxGATSBY_前缀的环境变量会被 Gatsby 注入到浏览器端代码中因此只适合放可发布密钥等公开信息STRIPE_SECRET_KEY仅用于 Node 端gatsby-config/gatsby-node的插件配置。同时确保.gitignore排除所有.env.*文件防止密钥泄露# .gitignore .env .env.development .env.production查询价格数据创建src/components/Products/Products.js用 GraphQL 查询allStripePrice节点。你可以在 GraphiQL 中验证查询并查看返回的数据结构// src/components/Products/Products.js import React from react import { graphql, useStaticQuery } from gatsby import ProductCard from ./ProductCard const Products () { const { prices } useStaticQuery(graphql query ProductPrices { prices: allStripePrice( filter: { active: { eq: true } } sort: { unit_amount: ASC } ) { edges { node { id active currency unit_amount product { id name } } } } } ) // 按商品分组价格 const products {} for (const { node: price } of prices.edges) { const product price.product if (!products[product.id]) { products[product.id] product products[product.id].prices [] } products[product.id].prices.push(price) } return ( div {Object.keys(products).map(key ( ProductCard key{products[key].id} product{products[key]} / ))} /div ) } export default Products创建src/pages/advanced.js导入Products /访问http://localhost:8000/advanced/即可看到商品列表见 advanced.js。抽取 getStripe 单例工具当多个页面/组件都要使用 Stripe.js 时建议把loadStripe抽成导出getStripe单例的工具函数见 stripejs.js// src/utils/stripejs.js /** * This is a singleton to ensure we only instantiate Stripe once. */ import { loadStripe } from stripe/stripe-js let stripePromise const getStripe () { if (!stripePromise) { stripePromise loadStripe(process.env.GATSBY_STRIPE_PUBLISHABLE_KEY) } return stripePromise } export default getStripe商品卡片与动态价格选择创建src/components/Products/ProductCard.js完整代码见 ProductCard.js为每个商品渲染一张卡片下拉框列出该商品的所有价格用Intl.NumberFormat把unit_amount单位分格式化为带货币符号的金额点击 BUY ME 按钮后从表单读取所选价格 ID 并重定向到 Checkoutconst formatPrice (amount, currency) { let price (amount / 100).toFixed(2) let numberFormat new Intl.NumberFormat([en-US], { style: currency, currency: currency, currencyDisplay: symbol, }) return numberFormat.format(price) } const handleSubmit async event { event.preventDefault() setLoading(true) const price new FormData(event.target).get(priceSelect) const stripe await getStripe() const { error } await stripe.redirectToCheckout({ mode: payment, lineItems: [{ price, quantity: 1 }], successUrl: ${window.location.origin}/page-2/, cancelUrl: ${window.location.origin}/advanced, }) if (error) { console.warn(Error:, error) setLoading(false) } }购物车功能如需为 Gatsby 站点增加购物车能力可使用 use-shopping-cart 库它能在组件与页面间维持购物车状态甚至把购物车状态持久化到localStorage并提供了 Gatsby 示例。测试支付使用带test字样的密钥即处于测试模式Stripe 提供了专用的测试卡号来覆盖不同的结算场景如成功、被拒、需 3DS 验证等。这意味着你可以在不产生真实扣款的前提下端到端验证 Checkout 流程。生产上线前请务必切换为 live 密钥并激活账户。更多资源本仓库的 Gatsby E-commerce Tutorial逐步讲解本文两种示例的完整教程ecommerce-tutorial-with-stripe 示例可直接运行参考的完整实现包含 checkout.js、Products.js、ProductCard.js 等核心组件以及 package.json 中展示的依赖清单stripe/stripe-js、gatsby-source-stripe等Gatsby 环境变量文档深入了解GATSBY_前缀环境变量的行为与作用域Stripe 官方网站、Stripe API 文档与 Stripe 测试文档系统了解平台能力、接口细节与测试工具。【免费下载链接】gatsbyReact-based framework with performance, scalability, and security built in.项目地址: https://gitcode.com/gh_mirrors/ga/gatsby创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
