laravel 13 + postgresql + pgvector 索引创建失败，90% 是因误用 mysql 风格语法、未显式指定 gin/gist 索引类型及 vector_opclass（如 vector_cosine_ops），或向量字段未用 $table->vector('embedding', 1536) 正确声明，导致索引静默失效或建表报错。
直接说结论：Laravel 13 + PostgreSQL + pgvector 索引创建失败，90% 不是 pgvector 本身的问题，而是迁移中误用了 MySQL 风格的索引语法，或没指定正确的索引类型和操作符类。
pgvector 的索引必须显式指定 GIN/GIST 和 opclass
PostgreSQL 的向量索引不是普通 B-tree，不能用 $table->index('embedding') 这种写法——Laravel 默认生成的是 B-tree 索引，而 pgvector 要求的是 GIN（用于 vector_cosine_ops）或 GIST（用于 vector_l2_ops / vector_ip_ops）。不指定类型，迁移会静默创建失败，或建出无效索引。
- 正确做法是在迁移中用原生 SQL 或
DB::statement()手动建索引：DB::statement('CREATE INDEX idx_items_embedding_cos ON items USING GIN (embedding vector_cosine_ops)'); - 如果坚持用 Schema 构建器，得绕过 Laravel 的抽象层：
Schema::table('items', function (Blueprint $table) { $table->index('embedding', 'idx_items_embedding_cos', 'gin'); });但注意：这个'gin'第三个参数仅在 Laravel 10+ 且底层驱动支持时才生效，PG 驱动默认不认，实际仍可能 fallback 到 B-tree - 别漏掉 opclass —— 比如用
cosine_distance查询却建了vector_l2_ops索引，查询完全不走索引
迁移里混用 foreignId() 或 unsignedBigInteger() 导致字段类型不匹配
pgvector 要求向量列是 vector(n) 类型（比如 vector(1536)），但如果你在迁移里写了 $table->foreignId('user_id') 或 $table->unsignedBigInteger('embedding')，PostgreSQL 会报错：类型不存在、无法隐式转换，甚至直接中断迁移。
- 向量字段必须用 pgvector 提供的类型声明：
$table->vector('embedding', 1536); // Laravel 13 原生支持，前提是已启用 pgvector 扩展 - 确认 PostgreSQL 已执行
CREATE EXTENSION IF NOT EXISTS vector;，否则vector类型根本不可用 - 别在同一个迁移里先建表再
DB::statement('CREATE EXTENSION...')—— 扩展必须在迁移开始前就存在，否则vector类型解析失败
EXPLAIN 显示“Seq Scan”但你确信建了索引？检查是否命中 opclass
即使 pg_indexes 里能看到索引名，EXPLAIN SELECT ... WHERE embedding '[...]' 仍显示 <code>Seq Scan，大概率是查询操作符和索引 opclass 不匹配。
- 用
（余弦距离）就必须配vector_cosine_ops；用（L2）就配vector_l2_ops；用（内积）配vector_ip_ops - 检查索引定义：
SELECT indexdef FROM pg_indexes WHERE tablename = 'items' AND indexname = 'idx_items_embedding_cos';
确认输出里包含vector_cosine_ops - pgvector 不支持在同一个列上建多个 opclass 索引，删旧索引再重建：
DROP INDEX idx_items_embedding_cos;
Laravel 13 的迁移回滚不自动删 pgvector 索引
运行 php artisan migrate:rollback 后，自定义的 GIN/GIST 索引还在数据库里，下次 migrate 会因“索引已存在”报错，比如 relation "idx_items_embedding_cos" already exists。
- 回滚逻辑必须手动补全：
public function down(Blueprint $table): void { DB::statement('DROP INDEX IF EXISTS idx_items_embedding_cos'); } - 别依赖
$table->dropIndex()—— 它只处理 Laravel 管理的 B-tree 索引，对 GIN/GIST 无效 - 上线前务必在测试库执行完整 migrate → rollback → migrate 流程，验证索引可重建
最易被忽略的一点：pgvector 索引生效的前提是查询条件里**不能有函数包裹向量列**。比如 WHERE normalize(embedding) ? 就会让索引失效——得把归一化逻辑移到写入侧，而不是查的时候算。
