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 提供了骨架，但填充肌肉——比如退款审批流、欠费用户降级策略、多币种税务计算——全得自己搭。
