Laravel Pennant 是运行时可变、作用域明确、默认持久化的特性控制原语，非简单开关插件；安装后必须执行 php artisan pennant:install 和 php artisan migrate，否则 Feature::active() 静默返回 false。
直接上结论：Laravel Pennant 不是“开关插件”，它是运行时可变、作用域明确、默认持久化、与 Laravel 生态深度对齐的特性控制原语。用错地方或跳过初始化步骤，Feature::active() 会静默返回 false，而你根本收不到报错。
安装后必须跑 php artisan pennant:install 和 php artisan migrate
很多人卡在这一步——以为 composer require laravel/pennant 就完事了。其实 Pennant 默认使用 database 驱动，但不会自动建表。不执行这两个命令，features 表不存在，所有 active() 调用都会 fallback 到未定义行为（多数情况是 false），且无日志、无异常。
注意：php artisan vendor:publish --provider="Laravel\Pennant\PennantServiceProvider" 已被弃用，Laravel 11+ 和 Pennant 2.x 推荐直接用 pennant:install 命令，它会自动发布迁移 + 配置 + 默认驱动设置。
- 执行前确认
config/pennant.php已生成，里面'driver' => 'database'是默认值 - 如果想临时用内存测试（比如 PHPUnit），可改配置为
'driver' => 'array'，但上线前务必切回database或redis -
features表结构极简：只有scope（JSON）、name、value、expires_at四个字段，别手动改
Feature::define() 的闭包参数不是可选的，必须匹配作用域类型
常见错误：在 AppServiceProvider::boot() 里写 Feature::define('beta-ui', fn () => true)，然后在控制器里调用 Feature::for($user)->active('beta-ui') —— 结果永远 false。因为闭包没声明接收 $user，Pennant 在解析时发现作用域类型不匹配，直接跳过执行，用默认值（false）填充。
正确写法必须显式声明参数类型：
Feature::define('beta-ui', function (User $user) {
return $user->hasRole('beta_tester') || $user->id === 123;
});
- 如果作用域是租户（
Tenant），闭包就要写function (Tenant $tenant) - 如果想支持多类型作用域（比如既支持 User 又支持 Tenant），得用
mixed+ 手动类型判断，但不推荐——易出错且破坏类型安全 - 闭包只在首次检查该作用域+功能组合时执行；后续读取走数据库缓存，所以闭包里别放副作用逻辑（如发通知、写日志）
Blade 中用 @feature 指令比手写 @if(Feature::active(...)) 更安全
手写 @if 容易漏掉作用域绑定。比如当前用户是 $user，但你写了 @if(Feature::active('new-search'))，Pennant 会尝试用 null 当作用域去查，结果不可控。
Laravel Cloud（cloud.laravel.com）。此技能用于处理所有 Laravel Cloud 请求，包括搜索和读取数据。只要任务涉及 Laravel Cloud，即使用此技能。
@feature 是语法糖，底层自动注入当前认证用户（Auth::user()），等价于 Feature::for(Auth::user())->active(...)，且做了空值保护：
@feature('new-search')
<div class="search-v2">...</div>
@else
<div class="search-v1">...</div>
@endfeature
- 如果当前没登录用户，
@feature默认不渲染内容（即静默跳过），不会抛异常 - 需要指定非默认作用域（比如按请求头里的
X-Tenant-ID查），就得回到 PHP 层用Feature::for($tenant)->active() -
@feature不支持传参给闭包，所有逻辑必须在define()时写死
Feature::for($user)->activate() 是覆盖，不是设置默认值
这是最常被误解的一点：调用 activate() 或 deactivate() 不是在“配置规则”，而是在“覆盖当前用户的已存储值”。它写入的是 features 表中该用户+功能的记录，优先级高于 define() 里的闭包逻辑。
典型误用场景：你想让所有管理员默认开启某功能，于是写：
// ❌ 错！这只会覆盖当前请求的 $user，其他管理员不受影响
if ($user->isAdmin()) {
Feature::for($user)->activate('admin-tools');
}
正确做法是把规则写进 define() 闭包里：
Feature::define('admin-tools', function (User $user) {
return $user->isAdmin();
});
-
activate()适合定向灰度：比如运营同学要给客户 ID 为 888 的用户提前开新功能，就手动调一次 -
forget()是关键逃生通道：覆盖后想恢复自动计算？调它即可删掉那条覆盖记录 - 批量操作（如全量激活某功能）要用
Feature::activateForAll()，但它不触发闭包，而是直接批量写库，慎用
真正难的从来不是“怎么开开关”，而是想清楚每个 define() 闭包的边界条件——用户没登录怎么办？租户没关联模型怎么办？闭包里抛异常会不会让整个页面挂掉？这些细节不提前兜住，特性开关反而会变成线上故障放大器。
