Laravel Scout 集成 Typesense 报错：Parameter fields is required

以下是针对该问题的排查和解决步骤：

1. 确认Scout配置文件结构正确性 #

错误核心是Typesense客户端未接收到创建集合所需的fields参数，大概率是模型的collection-schema配置未被正确读取。请确保config/scout.php中，模型配置严格放在typesense数组下的models键内，示例结构如下：

return [
    // 其他Scout配置...
    'driver' => env('SCOUT_DRIVER', 'typesense'),
    // ...
    'typesense' => [
        'api_key' => env('TYPESENSE_API_KEY', 'your_key'),
        'nodes' => [
            [
                'host' => env('TYPESENSE_HOST', 'localhost'),
                'port' => env('TYPESENSE_PORT', '8108'),
                'protocol' => env('TYPESENSE_PROTOCOL', 'http'),
            ],
        ],
        'nearest_node' => [
            'host' => env('TYPESENSE_HOST', 'localhost'),
            'port' => env('TYPESENSE_PORT', '8108'),
            'protocol' => env('TYPESENSE_PROTOCOL', 'http'),
        ],
        'connection_timeout_seconds' => 2,
        // 模型配置必须放在models数组内
        'models' => [
            App\Models\Module::class => [
                'collection-schema' => [
                    'fields' => [
                        ['name' => 'id', 'type' => 'string'],
                        ['name' => 'uuid', 'type' => 'string'],
                        ['name' => 'created_at', 'type' => 'int64'],
                    ],
                    'default_sorting_field' => 'created_at',
                ],
                'search-parameters' => [
                    'query_by' => 'uuid'
                ],
            ],
        ],
    ],
];

不少用户会误将模型配置放在typesense数组外，导致驱动无法读取fields配置。

2. 验证模型命名空间与配置匹配 #

检查配置中Module::class的命名空间是否与实际模型完全一致，比如模型文件路径是app/Models/Module.php，则配置中必须引用App\Models\Module::class，注意大小写、命名空间拼写错误。

3. 检查驱动版本兼容性 #

确保laravel/scout、laravel/scout-typesense-driver和typesense/typesense-php版本相互兼容。旧版本驱动可能存在配置读取的bug，执行以下命令更新依赖：

composer update laravel/scout laravel/scout-typesense-driver typesense/typesense-php

4. 手动创建集合测试 #

先通过API手动创建目标集合，排除Typesense服务本身的问题：

curl -X POST http://localhost:8108/collections \
  -H "Content-Type: application/json" \
  -H "X-TYPESENSE-API-KEY: your_api_key" \
  -d '{
    "name": "modules",
    "fields": [
      {"name": "id", "type": "string"},
      {"name": "uuid", "type": "string"},
      {"name": "created_at", "type": "int64"}
    ],
    "default_sorting_field": "created_at"
  }'

如果手动创建成功，再执行php artisan scout:import App\Models\Module，若不再报错，说明驱动自动创建集合时未正确读取配置，回到第一步确认配置结构。

5. 确认.env驱动设置 #

检查.env文件中是否正确设置：

SCOUT_DRIVER=typesense

若驱动设置为其他值（如algolia、meilisearch），Typesense的配置不会被加载。

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