Laravel如何集成支付系统Stripe_Laravel Cashier扩展包安装与订阅功能【实战】

Stripe 在 Laravel 中需通过 Cashier 实现安全合规的订阅管理；直接调用 API 易出错，Cashier v14+ 要求 Laravel 10+、PHP 8.1+ 和 stripe-php v12+，须严格校验环境、配置密钥、运行迁移、手动创建 Stripe 产品与价格、正确处理 Webhook 及订阅生命周期陷阱。

Stripe 在 Laravel 中不是开箱即用的，必须通过 Cashier 才能安全、合规地处理订阅和发票；直接手写 Stripe API 调用极易出错，尤其在 Webhook 验证、状态同步、试用期续订等环节。

安装 Cashier 并配置 Stripe 密钥

Cashier v14+ 仅支持 Laravel 10+ 和 PHP 8.1+，且强制要求使用 Stripe 的 stripe-php v12+。别跳过环境校验，否则运行时会抛出 Class 'Stripe\Stripe' not found 或 Undefined array key 'secret'。

• 运行 composer require laravel/cashier（自动拉取兼容当前 Laravel 版本的 Cashier）
• 在 .env 中设置 STRIPE_KEY=sk_test_... 和 STRIPE_SECRET=sk_test_...，注意 STRIPE_WEBHOOK_SECRET 必须单独配置（后续 Webhook 必用）
• 执行 php artisan cashier:install —— 它会发布迁移、注册服务提供者，并修改 App\Models\User 实现 Billable 接口
• 别漏掉数据库迁移：php artisan migrate，Cashier 依赖 subscriptions、subscription_items 等表

创建 Stripe 产品与价格并同步到 Laravel

Cashier 不管理 Stripe 后台的产品（Product）和价格（Price），这些必须手动在 Stripe Dashboard 创建。Cashier 只通过 price_id 关联，一旦后台删掉 Price，用户续订就会失败并报 InvalidRequestException: No such price。

• 在 Dashboard 创建 Product（如 “Pro Plan”），再为其添加 recurring Price（如 price_1Qx...xyz），务必选中 “Recurring” 且 Currency 与应用一致（如 usd）
• 代码中调用订阅时，传入的是 Stripe 的 price_id 字符串，不是本地 ID：

  auth()->user()->newSubscription('default', 'price_1Qx...xyz')->create($paymentMethodId);

• 如果需多价格（年付/月付），每个 Price 是独立 ID，订阅升级时用 swap() 切换，不是改字段

处理 Stripe Webhook 以保证状态实时准确

用户在 Stripe 页面取消订阅、付款失败、发票生成等事件，不会自动同步到你的数据库 —— 全靠 Webhook。不配或配错 STRIPE_WEBHOOK_SECRET，会导致 Signature verification failed 错误，所有事件被丢弃。

• 在 Dashboard 的 Webhook 设置页添加 endpoint（如 https://yoursite.com/webhook/stripe），复制生成的 Signing secret 填入 .env 的 STRIPE_WEBHOOK_SECRET
• Cashier 自带路由 Route::stripeWebhooks('webhook/stripe')，无需手写控制器，但必须确保该路由未被中间件拦截（特别是 CSRF）
• 关键事件监听：在 app/Providers/EventServiceProvider.php 的 $listen 中注册：

  use Laravel\Cashier\Events\WebhookReceived;
  'events' => [
      WebhookReceived::class => ['App\Listeners\HandleStripeWebhook'],
  ],

  ，然后在监听器里用 $event->payload['type'] 分支处理 invoice.payment_failed、customer.subscription.deleted 等

订阅生命周期中的典型陷阱

很多“功能正常”的订阅逻辑，在真实场景下会崩：用户换卡、跨时区试用结束、发票税号变更、免费试用后自动扣款失败……这些问题 Cashier 不自动兜底，得你补。

• trial_days 是服务器端时间，不是 Stripe 时间；若用户晚于试用结束日首次访问，subscribed() 可能仍返回 true，但实际已过期 —— 应结合 onTrial() 和 trialEndsAt 字段双重判断
• 更换支付方式必须用 updatePaymentMethod($paymentMethodId)，不能只改 cards 表；否则下次扣款仍走旧卡
• 调用 cancelNow() 会立即终止订阅（无宽限期），而 cancel() 是到期取消；后者更常用，但用户看不到“将在 X 日失效”的提示，需前端主动查 endsAt
• 发票 PDF 生成依赖 laravel/cashier-stripe 的 invoice()->download()，但默认不存档；如需长期可查，得监听 invoice.payment_succeeded 后调用 $invoice->storePdf()

真正难的不是接通 Stripe，而是让每次扣款、每张发票、每个状态变更都可追溯、可对账、可人工干预。Cashier 提供了骨架，但填充肌肉——比如退款审批流、欠费用户降级策略、多币种税务计算——全得自己搭。