Laravel Jetstream 安装后 Fortify 服务提供者缺失问题解析

问题现象

在使用 Laravel Jetstream 进行项目初始化时，部分开发者遇到了一个典型错误："Target [Laravel\Fortify\Contracts\UpdatesUserPasswords] is not instantiable"。这个错误通常发生在执行测试或尝试使用密码更新功能时，表明系统无法实例化 Fortify 相关的契约接口。

问题根源

经过深入分析，发现这个问题源于服务提供者注册环节的缺陷。具体来说：

1. 当使用 jetstream:install 命令安装 Jetstream 时，安装程序会尝试将 App\Providers\FortifyServiceProvider 添加到 bootstrap/providers.php 文件中

2. 安装过程中会调用两次 ServiceProvider::addProviderToBootstrapFile() 方法

3. 当 OPcache 启用时（Sail 环境默认启用），第二次调用会读取第一次调用缓存的 providers 文件，导致无法识别第一次的修改

4. 最终结果是 FortifyServiceProvider 没有被正确注册到应用中

技术细节

这个问题特别容易在以下环境中复现：

• 使用 Laravel Sail 作为开发环境
• OPcache 扩展已启用
• 执行自动化测试时

错误堆栈显示系统在尝试解析依赖时失败，因为 Fortify 的相关服务没有被正确注册。这影响了包括用户注册、密码更新等多个核心功能。

解决方案

目前有两种解决方法：

1. 手动修复：编辑 bootstrap/providers.php 文件，确保包含以下内容：

App\Providers\FortifyServiceProvider::class,

2. 等待官方修复：Laravel 框架团队已经提交了修复 PR，将在后续版本中解决这个 OPcache 相关的问题

最佳实践建议

对于使用 Jetstream 的开发者，建议：

1. 安装完成后立即检查 bootstrap/providers.php 文件
2. 在开发环境中暂时禁用 OPcache 进行安装
3. 运行基础功能测试验证安装完整性
4. 关注 Laravel 框架更新，及时应用修复版本

这个问题虽然表现明显，但解决方法简单，不会对项目造成长期影响。理解其背后的机制有助于开发者更好地处理类似的服务注册问题。