Laravel Telescope预发环境出现__PHP_Incomplete_Class_Name错误求助

问题背景 #

本地Sail环境中Laravel Telescope运行正常，仅修改了两处配置：

1. config/telescope.php 路径配置：

'path' => env('TELESCOPE_PATH', 'admin/telescope'),

2. App\Providers\TelescopeServiceProvider 权限Gate配置：

protected function gate(): void
{
    Gate::define('viewTelescope', function ($user) {
        return $user->operations()->contains(
            cache()->remember('viewTelescope', 1440, function () {
                return Operation::updateOrCreate([
                    "operation" => "admin/telescope/view",
                    "description" => "Can view Telescope"
                ])->operation;
            })
        );
    });
}

但在标记为production的预发环境中，日志出现__PHP_Incomplete_Class_Name错误，涉及Laravel\Telescope\Jobs\ProcessPendingUpdates和Laravel\Telescope\EntryUpdate类。

错误日志 #

Job is incomplete class: {
    "__PHP_Incomplete_Class_Name": "Laravel\\Telescope\\Jobs\\ProcessPendingUpdates",
    "pendingUpdates": [
        {
            "__PHP_Incomplete_Class_Name": "Laravel\\Telescope\\EntryUpdate",
            "uuid": "99534bfc-841e-4368-bc84-e495cc38e8b6",
            "type": "job",
            "changes": {
                "status": "processed",
                "updated_batch_id": "99534bfe-1359-4698-a3ce-96701e1de445"
            },
            "tagsChanges": {
                "removed": [],
                "added": []
            }
        },
        {
            "__PHP_Incomplete_Class_Name": "Laravel\\Telescope\\EntryUpdate",
            "uuid": "99534bfc-7920-4e0f-b323-27c6accd548f",
            "type": "batch",
            "changes": {
                "id": "99534bfc-7920-4e0f-b323-27c6accd548f",
                "name": "records",
                "totalJobs": 15,
                "pendingJobs": 2,
                "processedJobs": 13,
                "progress": 87,
                "failedJobs": 0,
                "options": [],
                "createdAt": "2023-06-03T22:12:41.000000Z",
                "cancelledAt": null,
                "finishedAt": null,
                "updated_batch_id": "99534bfe-1359-4698-a3ce-96701e1de445"
            },
            "tagsChanges": {
                "removed": [],
                "added": []
            }
        }
    ],
    "attempt": 0,
    "delay": "2023-06-03T22:12:52.783591Z"
}

失败任务信息 #

{
    "uuid": "3ab7310f-f531-4d47-bb28-10ec2198d8a0",
    "displayName": "Laravel\\Telescope\\Jobs\\ProcessPendingUpdates",
    "job": "Illuminate\\Queue\\CallQueuedHandler@call",
    "maxTries": null,
    "maxExceptions": null,
    "failOnTimeout": false,
    "backoff": null,
    "timeout": null,
    "retryUntil": null,
    "data": {
        "commandName": "Laravel\\Telescope\\Jobs\\ProcessPendingUpdates",
        "command": "O:44:\"Laravel\\Telescope\\Jobs\\ProcessPendingUpdates\":3:{s:14:\"pendingUpdates\";O:29:\"Illuminate\\Support\\Collection\":2:{s:8:\"�*�items\";a:2:{i:0;O:29:\"Laravel\\Telescope\\EntryUpdate\":4:{s:4:\"uuid\";s:36:\"99534bfc-841e-4368-bc84-e495cc38e8b6\";s:4:\"type\";s:3:\"job\";s:7:\"changes\";a:2:{s:6:\"status\";s:9:\"processed\";s:16:\"updated_batch_id\";s:36:\"99534bfe-1359-4698-a3ce-96701e1de445\";}s:11:\"tagsChanges\";a:2:{s:7:\"removed\";a:0:{}s:5:\"added\";a:0:{}}}i:1;O:29:\"Laravel\\Telescope\\EntryUpdate\":4:{s:4:\"uuid\";s:36:\"99534bfc-7920-4e0f-b323-27c6accd548f\";s:4:\"type\";s:5:\"batch\";s:7:\"changes\";a:12:{s:2:\"id\";s:36:\"99534bfc-7920-4e0f-b323-27c6accd548f\";s:4:\"name\";s:7:\"records\";s:9:\"totalJobs\";i:15;s:11:\"pendingJobs\";i:2;s:13:\"processedJobs\";i:13;s:8:\"progress\";d:87;s:10:\"failedJobs\";i:0;s:7:\"options\";a:0:{}s:9:\"createdAt\";O:22:\"Carbon\\CarbonImmutable\":3:{s:4:\"date\";s:26:\"2023-06-03 22:12:41.000000\";s:13:\"timezone_type\";i:3;s:8:\"timezone\";s:3:\"UTC\";}s:11:\"cancelledAt\";N;s:10:\"finishedAt\";N;s:16:\"updated_batch_id\";s:36:\"99534bfe-1359-4698-a3ce-96701e1de445\";}s:11:\"tagsChanges\";a:2:{s:7:\"removed\";a:0:{}s:5:\"added\";a:0:{}}}}s:28:\"�*�escapeWhenCastingToString\";b:0;}s:7:\"attempt\";i:0;s:5:\"delay\";O:25:\"Illuminate\\Support\\Carbon\":3:{s:4:\"date\";s:26:\"2023-06-03 22:12:52.783591\";s:13:\"timezone_type\";i:3;s:8:\"timezone\";s:3:\"UTC\";}}\"
    },
    "telescope_uuid": null,
    "id": "rCFQJOBIQRM6ScbagN7wnaViB8884jol",
    "attempts": 0
}

解决步骤 #

1. 确保Telescope在生产环境被正确加载 #

Laravel默认不会在生产环境自动注册Telescope服务提供者，需手动添加到config/app.php的providers数组：

App\Providers\TelescopeServiceProvider::class,

或在App\Providers\AppServiceProvider的register方法中按需注册：

public function register()
{
    if ($this->app->environment('production')) {
        $this->app->register(\Laravel\Telescope\TelescopeServiceProvider::class);
        $this->app->register(App\Providers\TelescopeServiceProvider::class);
    }
}

2. 清理队列中的旧任务 #

__PHP_Incomplete_Class错误通常是因为队列中存在序列化的任务，但对应类未被加载，需清空旧任务：

# 清空默认队列
php artisan queue:clear

# 若使用Redis队列
php artisan queue:clear redis

3. 优化类加载（生产环境必备） #

运行以下命令清理并重建类缓存，确保所有类被正确加载：

php artisan optimize:clear
php artisan optimize

4. 确认Telescope在生产环境启用 #

检查.env文件：

TELESCOPE_ENABLED=true

同时验证config/telescope.php中的启用配置：

'enabled' => env('TELESCOPE_ENABLED', true),

5. 重启队列Worker #

队列Worker可能缓存了旧的类信息，需重启生效：

php artisan queue:restart

内容的提问来源于stack exchange，提问作者lordisp