必须先完成模型加Billable、运行迁移、配置STRIPE_SECRET并清缓存，再使用Cashier；Laravel 11对应Cashier v15+，需显式指定版本，且Webhook路由须手动注册。
直接运行 composer require laravel/cashier 就能装上，但装完不能立刻用——多数报错都卡在后续配置没跟上，比如模型没加 Billable、迁移没跑、STRIPE_SECRET 没配对，或者 Laravel 版本和 Cashier 不兼容。
安装命令与版本对齐
Cashier 的主干版本严格绑定 Laravel 主版本。2026 年主流项目大概率是 Laravel 11.x，对应必须用 Cashier v15+：
-
composer require laravel/cashier:^15.0（显式指定，避免 Composer 自动降级） - 若项目还在 Laravel 10.x，用
laravel/cashier:^14.0；Laravel 9 请用^13.0 - 别手动 require stripe/stripe-php —— Cashier 已声明依赖，重复装反而容易冲突
- 装之前删掉
vendor/stripe/stripe-php（如果旧版手装过），防止 autoloader 冲突
迁移没跑 = createAsStripeCustomer() 直接报错
调用 $user->createAsStripeCustomer() 报 Call to undefined method，90% 是因为数据库缺字段，不是代码写错了：
- Laravel 11+：直接运行
php artisan cashier:install（它会自动发布并执行迁移） - Laravel 10 及更早：先
php artisan vendor:publish --tag="cashier-migrations"，再php artisan migrate - 迁移生成的表包括
subscriptions、subscription_items、payment_methods，但关键在users表是否加了stripe_id字段 —— Cashier 默认不改 users 表，得自己加或用cashier:install自动处理 - 如果已有用户数据，别漏掉
php artisan cashier:install --force（强制补字段）
STRIPE_SECRET 配错或没生效，Webhook 和支付全挂
环境变量看着写了，但 STRIPE_SECRET 实际为空，会导致 createAsStripeCustomer() 返回 401、Webhook 验签失败、甚至本地测试时 Stripe SDK 抛出未捕获异常：
Laravel Cloud
下载
Laravel Cloud（cloud.laravel.com）。此技能用于处理所有 Laravel Cloud 请求，包括搜索和读取数据。只要任务涉及 Laravel Cloud，即使用此技能。
-
.env里必须写成STRIPE_SECRET=sk_test_...（注意是sk_开头的 secret key，不是 publishable key） - 确认
config/services.php中stripe数组存在且 key 名拼写正确：'secret' => env('STRIPE_SECRET')，不是stripe_secret或STRIPE_API_SECRET - 修改 .env 后清缓存：
php artisan config:clear，否则 config() 读的还是旧值 - Webhook 路由不注册 = /webhook/stripe 404，必须手动加路由：
Route::post('/webhook/stripe', [\App\Http\Controllers\StripeWebhookController::class, 'handleWebhook']);
Billable trait 没加，所有订阅方法都不可用
哪怕 migration 跑了、key 配对了，$user->subscription('monthly')->create($paymentMethod) 还是报错，大概率是模型没“激活” Cashier 功能：
- User 模型（或你实际用的 Billable 模型）必须 use
Laravel\Cashier\Billable，且在 class 定义里加上use Billable; - 别只写
use Billable忘了use Laravel\Cashier\Billable—— PHP 会找不到 trait - 如果你用了自定义用户模型（比如
App\Models\Customer），要在config/services.php的 stripe 配置里显式指定：'model' => \App\Models\Customer::class - 检查模型是否继承
Illuminate\Foundation\Auth\User或至少实现了Authenticatablecontract，否则 Cashier 内部的 guard 检查会失败
最容易被忽略的是：Cashier 不自动注册任何路由、不自动添加任何数据库字段到现有 users 表、也不校验你的 Stripe 密钥格式是否合法——它只在第一次调用客户创建逻辑时才真正连接 Stripe。线上环境密钥写错，可能直到用户点击“订阅”才暴露问题。
