Index 注解不能直接用于模型字段定义，因其是元数据类而非字段类型；正确用法是在 Meta.indexes 列表中声明 models.Index 实例。
为什么 Index 注解在 Django 4.2 中不能直接用于模型字段定义
因为 Index 是元数据类，不是字段类型，不能像 models.CharField 那样写在字段声明位置。Django 会忽略模型类体中孤立的 Index(...) 调用，也不会报错——这是最常被误踩的坑。
正确位置只有一处：模型的 Meta.indexes 列表。它必须是 list 类型，每个元素是 models.Index 实例。
常见错误写法示例（无效）：
class Order(models.Model):
user_id = models.IntegerField()
status = models.CharField(max_length=20)
created_at = models.DateTimeField()
<pre class='brush:python;toolbar:false;'># ❌ 错误：这行不会生效，Django 完全无视
Index(fields=['user_id', 'status'])</pre>如何用 models.Index 正确声明复合索引
必须显式导入并填入 fields 元组，字段顺序影响查询效率和覆盖能力。Django 4.2 支持表达式索引、降序索引、条件索引等进阶用法，但基础复合索引只需关注字段组合与顺序。
立即学习“Python免费学习笔记（深入）”；
-
fields是元组，不是列表；单字段也要写成('field_name',)（注意末尾逗号） - 字段顺序应匹配高频查询的 WHERE 子句顺序，例如
WHERE user_id = ? AND status = ?对应('user_id', 'status') - 如果查询常带
ORDER BY created_at DESC，可加models.Index(fields=['user_id', '-created_at'])，但注意降序索引在 SQLite 中不生效 - 索引名默认由 Django 自动生成（如
order_user_id_status_123abc_idx），如需自定义，传入name='idx_order_user_status'，且必须唯一、长度 ≤ 30
正确写法示例：
快速生成专业的 Python 脚本和应用代码。一键创建完整项目结构，支持CLI、API、爬虫、Bot、Django等多种项目类型，包含完整的项目结构、配置文件、依赖管理、测试、README和文档。
from django.db import models
<p>class Order(models.Model):
user_id = models.IntegerField()
status = models.CharField(max_length=20)
created_at = models.DateTimeField()</p><pre class='brush:python;toolbar:false;'>class Meta:
indexes = [
models.Index(fields=['user_id', 'status']),
models.Index(fields=['user_id', '-created_at'], name='idx_order_user_created'),
]</pre>运行迁移时为什么没生成 SQL 或提示“no changes detected”
Django 的索引变更检测依赖于 Meta.indexes 内容与当前数据库状态的比对。如果之前已有同名索引（比如手动建过或旧迁移残留），或者字段类型/约束发生过变化但未同步更新索引定义，makemigrations 可能跳过生成。
排查步骤：
- 执行
python manage.py showmigrations确认是否有未应用的索引迁移 - 检查数据库是否已存在同名索引：
SELECT indexname FROM pg_indexes WHERE tablename = 'your_app_order';（PostgreSQL） - 若确认需要强制重生成，可删掉最近一条索引相关迁移文件，再运行
makemigrations --empty your_app手动补上migrations.AddIndex(...) - 注意：SQLite 不支持
ADD INDEX以外的索引操作，修改fields顺序会导致 Django 删除重建，有性能风险
复合索引生效但查询仍慢？检查是否命中了最左前缀原则
Django 生成的 B-tree 索引遵循最左前缀规则：只有查询条件包含索引最左侧连续字段时才能使用该索引。例如索引 ('user_id', 'status', 'created_at')，以下查询能命中：
WHERE user_id = 123WHERE user_id = 123 AND status = 'paid'WHERE user_id = 123 AND status = 'paid' AND created_at > '2023-01-01'
但这些查询无法使用该索引：
-
WHERE status = 'paid'（跳过了user_id） -
WHERE status = 'paid' AND created_at > '2023-01-01'（缺少最左字段） -
WHERE user_id = 123 AND created_at > '2023-01-01'（跳过了中间的status，除非该字段在 DB 中有统计信息且优化器选择跳过）
用 EXPLAIN QUERY PLAN（SQLite）或 EXPLAIN (ANALYZE)（PostgreSQL）验证实际执行计划，别只信索引存在就等于生效。
字段顺序一旦定下就很难调整，尤其当表数据量大时，重建索引会锁表。上线前务必用真实数据集压测关键查询路径。
