Laravel Cashier 是需自主设计链路的计费工具包，非开箱即用SaaS系统；多价格订阅须全用price_id、属同一product；addPrice/addMeteredPrice生效时机影响账期；cancel()不立即停服，需cancelNow()；业务权限校验不可依赖ends_at。
直接说结论：Laravel Cashier 不是“开箱即用”的 SaaS 订阅系统，而是一套需要你主动设计链路、补全边界逻辑的计费工具包。它帮你省掉 Stripe Webhook 解析、发票生成、订阅状态同步等样板代码，但不会替你决定“用户升级时要不要保留旧服务”“计量用量怎么防刷”“试用期结束前要不要发提醒邮件”。
创建多价格订阅时，newSubscription 的数组参数必须全是 Stripe 价格 ID（price_xxx），不能混用 plan ID
常见错误是把老版 Stripe Plan ID（如 plan_ght23）和新版 Price ID（price_1Qx...z）一起传给 newSubscription，结果抛出 Invalid price id 或静默失败。
- Stripe Dashboard 中所有新创建的价格都以
price_开头；Plan ID 已被弃用，Cashier 12+ 完全不支持 - 多价格订阅本质是「一个 subscription 对应多个 active price items」，不是多个 plan 的叠加
- 如果想实现“基础版 + API 配额包 + 协作空间包”，就该在 Stripe 创建三个独立的
recurring类型 price，并在 Laravel 侧用['price_basic', 'price_api', 'price_collab']传入 - 注意：Cashier 不会校验这些 price 是否属于同一产品（product），但 Stripe 后台要求它们必须归属同一个 product 才能共存于一个 subscription
addPrice 和 addMeteredPrice 的触发时机影响账单周期与用量归属
往已有订阅里加价，不是“立刻生效”，而是取决于 price 的 billing scheme 和 anchor date 设置。尤其对计量计费（metered）价格，错误调用会导致用量被记到错误账期。
-
addPrice('price_id')默认在下一个 billing cycle 生效；若要立即生效，需显式传参：->addPrice('price_id', ['prorate' => true]) -
addMeteredPrice只是注册一个 metered item，不产生账单；真正计费依赖后续调用reportUsage，且reportUsage必须指定timestamp—— 如果漏传或传错，Stripe 会按当前时间归入最近 billing period，导致用量错乱 - 典型坑：用户在 7 月 15 日开通 metered 服务，但直到 8 月 2 日才第一次
reportUsage；若没传timestamp，Stripe 会把全部用量算进 8 月账单，而非从 7 月 15 日起分摊
取消订阅后，ends_at 字段不等于“服务终止时间”，真正的截止由 cancel_at_period_end 控制
很多开发者以为调用 $subscription->cancel() 就立刻停服，结果发现用户还能继续用到月底——这是因为 Cashier 默认使用 cancel_at_period_end=true 行为，符合 Stripe 的安全设计，但业务上常需干预。
-
$subscription->cancel()等价于 Stripe 的cancel_at_period_end: true，只改ends_at，不改服务状态 - 要立即停服，必须用：
$subscription->cancelNow()（对应 Stripe 的cancel_now: true），此时ends_at会被设为当前时间，且 Stripe 会立即关闭 access - 关键细节：即使调用了
cancelNow()，已生成但未支付的 invoice（比如当月 prorated 账单）仍会留在 Stripe 后台，需手动 void 或 mark as paid，否则影响财务对账
最易被忽略的点是：Cashier 不管理「业务侧服务开关」。它只同步 Stripe 的 subscription 状态，而你的应用是否允许用户访问高级功能，必须在 middleware 或 policy 中显式检查 $user->subscribed('main') 或 $user->subscription('main')->hasPrice('price_pro')，不能只依赖数据库里的 ends_at 值做判断——因为 Stripe 状态可能延迟同步，Webhook 处理失败时就会脱钩。
