Django的ORM用起来很舒服，但一旦在视图函数里实例化模型时参数写错，解释器会毫不客气地抛出TypeError。这类报错信息往往很长，包含unexpected keyword argument或者positional argument之类的描述，初学者看到容易发懵。其实Django模型的实例化过程有明确的参数匹配规则，只要搞清楚这些规则，绝大多数TypeError都能在几分钟内定位到原因。本文结合几个典型场景，把模型实例化的参数机制和常见错误逐一拆解。
一、理解Django模型实例化的参数匹配规则
Django中每个模型类都继承自models.Model，其__init__方法由Django自动生成，接收的参数与模型字段一一对应。假设定义了这样一个模型：
from django.db import models
class Article(models.Model):
title = models.CharField(max_length=100)
content = models.TextField()
views = models.IntegerField(default=0)
category = models.ForeignKey(
'Category',
on_delete=models.CASCADE,
related_name='articles'
)
def __str__(self):
return self.title实例化时，正确的写法是Article(title='标题', content='内容', category=cat)。这里要注意两点：第一，外键字段在数据库中的名字是category_id，但在实例化参数里必须写category，传入的应该是模型实例或者主键值；第二，字段参数必须全部用关键字形式传递，虽然Django允许位置参数，但位置参数的顺序取决于模型字段的定义顺序，一旦后期调整字段顺序，位置参数就会错位，引发难以排查的 bug。
另一个容易忽略的规则是：Django允许传入模型中不存在的参数，但会在__init__阶段把未知参数作为实例属性暂存，供ModelForm等机制使用，并不会立即报错。真正报错的是传入了既不是字段名、又不是属性名、也无法赋值的参数，此时会看到TypeError: Article() got unexpected keyword arguments。所以当看到这个报错，第一步就是核对参数名和模型字段名是否完全一致，包括拼写和大小写。
二、视图函数中三类高频TypeError场景
场景一：外键参数写错
这是出现频率最高的一类错误。视图函数中常见这样的写法：
from django.shortcuts import render, get_object_or_404
from .models import Article, Category
def create_article(request):
cat = get_object_or_404(Category, pk=1)
# 错误写法：使用了数据库列名 category_id 作为参数名
article = Article(
title='测试',
content='内容',
category_id=cat
)
article.save()
return render(request, 'ok.html')上面的代码会抛出TypeError，因为实例化时的合法参数名是category而非category_id。修正方式有两种：写成category=cat传入模型实例，或者写成category_id=cat.id传入主键整数值。两种写法都可以，但混用容易出错，建议团队统一风格。
场景二：多对多字段在实例化时赋值
多对多字段（ManyToManyField）在数据库层面依赖中间表，必须先有主键才能建立关联，所以不能在__init__里直接赋值：
def create_article(request):
article = Article(
title='测试',
content='内容',
category_id=1,
tags=[1, 2, 3] # 错误：tags是ManyToManyField，不能这样传
)正确做法是先保存实例拿到主键，再通过set方法建立多对多关联：
def create_article(request):
article = Article(title='测试', content='内容', category_id=1)
article.save()
article.tags.set([1, 2, 3]) # 传入主键列表或对象列表均可
return render(request, 'ok.html')注意set会全量替换关联，如果只想追加，应该用add方法。这种限制本质上是关系型数据库的约束反映到了ORM接口设计上，理解了这一点就不会觉得Django奇怪了。
场景三：自定义__init__或save方法签名冲突
有时开发者会在模型里重写save方法并添加自定义参数，或者继承时定义了自己的__init__，参数处理不当就会和Django内部的机制打架：
class Article(models.Model):
title = models.CharField(max_length=100)
def save(self, *args, **kwargs):
notify = kwargs.pop('notify', True)
super().save(*args, **kwargs)
if notify:
send_notification(self.title)这种写法在直接调用article.save()时没问题，但如果代码走到了Article.objects.create()或表单的save()，某些参数透传场景下可能因为签名不兼容抛出TypeError。稳妥的做法是在重写方法时始终保留*args, **kwargs并完整透传给父类，不要使用固定的位置参数签名。
三、快速定位与调试技巧
遇到TypeError时，先完整阅读报错堆栈的最后一行，Django会明确指出是哪个参数不被接受。然后在Django shell里验证模型行为：
python manage.py shell >>> from myapp.models import Article >>> [f.name for f in Article._meta.fields] ['id', 'title', 'content', 'views', 'category']
Article._meta.fields能列出所有字段的真实参数名，拿来和视图代码逐一比对，参数名拼写问题立刻现形。如果怀疑是自定义方法导致的，可以在堆栈里找到最先抛异常的那一帧，确认调用链是__init__还是save。
日常编码中还有两个习惯能显著减少这类错误：一是字段全部用关键字参数传递，杜绝位置参数带来的顺序隐患；二是在视图中统一使用ModelForm或CreateView处理数据创建，把字段赋值逻辑交给表单层，视图代码只关心业务流程。这样既减少了手写参数的机会，也顺便获得了数据校验能力，一举两得。
Django TypeError模型实例化视图函数修改时间：2026-09-15 16:32:38