Laravel Telescope 升级指南：从 3.x 到 5.x 的迁移要点与完整操作清单

• 开发者工具
• 可观测性
• 调试器

本篇指南基于当前仓库的 UPGRADE.md，系统梳理 Laravel Telescope（Laravel 框架的优雅调试助手）在跨主版本升级时的必要操作：包括每次升级都必须执行的资源发布与视图缓存清理、4.x 升 5.0 时迁移文件加载方式的重大变更，以及 3.x 升 4.0 时的 PHP 与 Laravel 版本门槛。文中所有命令与结论均对照 src 目录下的命令实现、TelescopeServiceProvider.php 的发布逻辑、composer.json 的依赖约束及 CHANGELOG.md 的版本记录逐一佐证，读完即可照单执行完成升级。

升级前的统一动作：发布资源并清理视图缓存

无论从哪个版本升级，官方都要求在升级完成后执行两条命令：

php artisan telescope:publish php artisan view:clear

第一条telescope:publish用于将 Telescope 的前端资源与配置文件发布到你的应用；第二条view:clear用于清理 Laravel 编译后的 Blade 视图缓存，避免旧的视图模板缓存干扰新版本页面。

telescope:publish到底做了什么

从 PublishCommand.php 的实现可以看到，该命令本身是一个轻量封装，内部依次调用两次vendor:publish：

• 以--tag=telescope-config发布配置文件（覆盖到应用的config/telescope.php），是否强制覆盖由--force选项决定；
• 以--tag=telescope-assets发布前端静态资源（发布到public/vendor/telescope），且始终强制覆盖（源码中固定传'--force' => true）。

命令签名telescope:publish {--force : Overwrite any existing files}中的--force选项，用于在发布配置文件时覆盖应用里已有的同名文件。实际发布映射定义在 TelescopeServiceProvider.php 的registerPublishing()方法中，完整的发布标签（tag）体系如下：

注意telescope:publish默认不会发布迁移文件与服务提供者（这些在安装或 5.0 升级场景中单独处理），它聚焦于"每次升级后刷新资源"这一职责，与你每次升级后执行它、再执行view:clear的官方建议完全对应。

从 4.x 升级到 5.0

迁移文件的加载方式发生根本变化

这是 5.0 升级中最需要留意的行为变更：Telescope 5.0 不再自动从自身迁移目录加载迁移文件。升级后需要显式执行以下命令，把迁移发布到你的应用：

php artisan vendor:publish --tag=telescope-migrations

发布成功后，迁移文件会进入应用的database/migrations目录，之后再照常运行数据库迁移即可：

php artisan migrate

从源码看，TelescopeServiceProvider.php 在注册发布时优先使用 Laravel 较新版本提供的publishesMigrations方法（否则回退到publishes），把包内 database/migrations 目录整体发布到database_path('migrations')，这正是--tag=telescope-migrations标签的来源。

迁移文件会创建哪些表

发布下来的迁移文件为 2018_08_08_100000_create_telescope_entries_table.php，升级到 5.0 后它会创建三张数据表：

• telescope_entries：核心条目表，包含自增sequence、uuid、batch_id、family_hash、type（如 request、query、exception 等条目类型）、content（JSON 长文本）等字段，并对uuid、batch_id、family_hash、created_at、['type', 'should_display_on_index']建有索引；
• telescope_entries_tags：条目标签表，以entry_uuid+tag为联合主键，entry_uuid外键级联删除；
• telescope_monitoring：被监控的 tag 列表（tag为主键）。

该迁移的getConnection()会读取config('telescope.storage.database.connection')（默认取DB_CONNECTION），意味着 Telescope 数据可以落在与应用主库不同的连接上，升级前若自定义过存储连接，迁移也会跟随该配置。

5.0 时代的版本与环境约束（以当前仓库为准）

需要说明的是，UPGRADE.md 中 5.0 一节并未列出独立的版本门槛，但当前仓库 composer.json 的依赖声明代表了 5.x 系列的实际要求：

• PHP：^8.0；
• Laravel 框架：^8.37|^9.0|^10.0|^11.0（其中 Laravel 11 支持正是在 v5.0.0 中引入的，见 CHANGELOG.md v5.0.0 条目）。

也就是说，即使你此前在 4.x 的 PHP 7.3 / Laravel 8 环境运行，升到 5.0 也需要先满足 PHP 8.0+ 与对应 Laravel 版本约束。另外从 InstallCommand.php 的实现可以看到，在 Laravel 11 及以上版本中，安装/升级时服务提供者通过ServiceProvider::addProviderToBootstrapFile()写入bootstrap/providers.php，而较老版本则采用修改config/app.php中providers数组的方式——如果你的应用正处在 Laravel 11 升级过程中，这一点值得同步关注。

从 3.x 升级到 4.0

最低 PHP 版本提升到 7.3

升级到 4.0 后，PHP 7.3 成为最低要求。这与 CHANGELOG.md 中 v4.0.0 的记录吻合：该版本移除了 PHP 7.2 支持。若你的服务器仍运行 PHP 7.2 或更低版本，需先升级运行时再执行 Telescope 升级。

最低 Laravel 版本提升到 8.0

4.0 同时把最低 Laravel 版本提升到 8.0。依据同样来自 CHANGELOG.md v4.0.0：该版本引入了 Laravel 8 支持与队列 Batches 支持，并移除了 Laravel 6 与 7 的支持。因此从 3.x 升级前，请确认项目已处于 Laravel 8.0 或更高版本，并确保 PHP 版本满足 7.3+。

升级完成后的验证与数据维护命令

完成主版本升级并发布资源后，可以借助 Telescope 自带的一组 Artisan 命令验证数据链路是否正常，并维护调试数据：

这些命令的实现均有对应源码与测试佐证：

• ClearCommand.php 通过注入ClearableRepository契约执行clear()，ClearCommandTest.php 验证其会清空telescope_entries与telescope_monitoring两张表；
• PruneCommand.php 以now()->subHours(hours)为时间界线裁剪旧数据，PruneCommandTest.php 验证了默认保留 24 小时、--hours可自定义、以及--keep-exceptions对异常数据的保留行为；
• PauseCommand.php 与 ResumeCommand.php 通过缓存键telescope:pause-recording（有效期为 30 天）控制 Telescope.php 中startRecording()的$shouldRecord开关，暂停后 Telescope 会停止落库但不会影响应用本身。

建议在升级后先执行一次telescope:clear清空旧版本遗留数据，再做一次真实请求或任务，打开/telescope页面确认各类条目（请求、查询、异常、任务、邮件等）能够正常写入与展示，从而确认迁移与资源发布均已生效。

升级检查清单

综合 UPGRADE.md 与仓库现状，给出如下可对照执行的升级清单：

1. 升级前：确认 PHP 与 Laravel 版本满足目标版本要求——升 4.0 需 PHP ≥ 7.3 且 Laravel ≥ 8.0；升 5.0 以当前仓库为准需 PHP ≥ 8.0 且 Laravel ≥ 8.37（推荐 9/10/11）。
2. 升级包版本：通过 Composer 将laravel/telescope更新到目标主版本。
3. 发布迁移（仅 5.0 起）：执行php artisan vendor:publish --tag=telescope-migrations，然后执行php artisan migrate完成三张表（telescope_entries、telescope_entries_tags、telescope_monitoring）的创建或结构更新。
4. 发布资源：执行php artisan telescope:publish，必要时加--force覆盖旧配置；该命令会同步发布config/telescope.php与public/vendor/telescope下的前端资源。
5. 清理视图缓存：执行php artisan view:clear，避免旧版编译视图残留。
6. 数据验证：执行telescope:clear清空旧数据，访问 Telescope 页面确认记录功能正常；如需要长期保留调试数据，可配置计划任务定期执行telescope:prune。

以上所有操作均只涉及你的应用项目本身，仓库（包括 UPGRADE.md、src/Console、TelescopeServiceProvider.php）均为只读参考；若在升级过程中遇到与版本门槛、迁移或资源发布相关的疑问，可随时回到 CHANGELOG.md 对照各主版本（v5.0.0、v4.0.0）的变更记录进行核验。

• 开发者工具
• 可观测性
• 调试器