Django 4.1 版本发行说明 — Django 6.0.4 documentation（2026）

创始人

2026-05-25 15:25:17

0次

Django 6.0.4 documentation

Home | Table of contents | Index | Modules

« previous | up | next »

Django 4.1 版本发行说明¶

2022 年 8 月 3 日

欢迎使用 Django 4.1！

这些发布说明涵盖了新功能，以及从 Django 4.0 或更早版本升级时需要注意的一些不兼容变更。我们已经开始了某些功能的弃用过程。

如果你要更新现有的项目，请看如何将 Django 更新至新的版本指南。

Python 兼容性¶

Django 4.1 支持 Python 3.8、3.9、3.10 和 3.11（从 4.1.3 开始）。我们 强烈建议 并且只官方支持每个系列的最新发布版本。

Django 4.1 新特性¶

基于类的视图的异步处理程序。¶

现在，视图的子类可以定义异步的 HTTP 方法处理程序：

import asyncio
from django.http import HttpResponse
from django.views import View


class AsyncView(View):
    async def get(self, request, *args, **kwargs):
        # Perform view logic using await.
        await asyncio.sleep(1)
        return HttpResponse("Hello async world!")

请参阅异步类视图以获取更多详细信息。

异步的 ORM 接口。¶

QuerySet 现在为所有数据访问操作提供了异步接口。这些接口的命名方式与现有的同步操作相同，但带有一个 a 前缀，例如 acreate()、aget() 等等。

新的接口允许您编写异步代码，而无需将 ORM 操作包装在 sync_to_async() 中：

async for author in Author.objects.filter(name__startswith="A"):
    book = await author.books.afirst()

值得注意的是，目前数据库操作仍然是同步的，但正在进行贡献工作，以将异步支持推向 SQL 编译器并集成异步数据库驱动程序。新的异步查询集接口目前为您封装了必要的 sync_to_async() 操作，将允许您的代码充分利用 ORM 异步支持的发展。

请参阅异步查询以获取详细信息和限制。

约束的验证¶

在 Meta.constraints 选项中定义的 Check、unique 和 exclusion 约束现在在模型验证期间进行检查。

表单渲染的可访问性¶

为了帮助使用屏幕阅读器和其他辅助技术的用户，从这个版本开始提供了基于

的新表单模板。这些模板提供比旧模板更可访问的导航，并能够正确地将相关控件（如单选列表）分组到字段集中。

推荐使用新模板，并且在 Django 5.0 中，当在模板中输出表单时（如 {{ form }}），新模板将成为默认的表单呈现样式。

为了方便采用新的输出样式，现在可以通过项目级别的 FORM_RENDERER 设置来配置默认的表单和表单集模板。

请查看下面的表单部分以获取完整的详细信息。

次要特性¶

`django.contrib.admin`¶

管理员深色模式 CSS 变量现在应用在一个单独的样式表和模板块中。
提供自定义 FieldListFilter 子类的 ModelAdmin 列表过滤器现在可以在使用 __in 查询时控制查询字符串值的分隔符，用于多个值的过滤。
管理员的 history view 现在支持分页。
相关的小部件包装现在有一个指向对象修改表单的链接。
AdminSite.get_app_list() 方法现在允许更改管理员首页上应用程序和模型的顺序。

`django.contrib.auth`¶

PBKDF2 密码哈希器的默认迭代次数从 320 , 000 增加到 390 , 000 。
RemoteUserBackend.configure_user() 方法现在允许将用户属性与远程系统（如 LDAP 目录）中的属性同步。

`django.contrib.gis`¶

The new GEOSGeometry.make_valid() method allows converting invalid geometries to valid ones.
GEOSGeometry.normalize() 的新参数 clone 允许创建几何图形的归一化克隆。

`django.contrib.postgres`¶

新的 BitXor() 聚合函数返回所有非空输入值的按位 XOR 的 int 值。
SpGistIndex 现在在 PostgreSQL 14+ 上支持覆盖索引。
ExclusionConstraint 现在在 PostgreSQL 14+ 上支持使用 SP-GiST 索引的覆盖排除约束。
新的 DateTimeRangeField 和 DecimalRangeField 的 default_bounds 属性允许为列表和元组输入指定边界。
ExclusionConstraint 现在允许使用 OpClass() 表达式指定操作符类。

`django.contrib.sitemaps`¶

默认的站点地图索引模板现在在可用时包括时间戳，通过新的 get_latest_lastmod() 方法。自定义站点地图索引模板应该根据调整后的上下文变量进行更新。

`django.contrib.staticfiles`¶

ManifestStaticFilesStorage 现在会将 CSS 源映射引用的路径替换为它们的哈希版本。

数据库后端¶

第三方数据库后端现在可以使用 DatabaseFeatures.minimum_database_version 属性指定数据库的最低要求版本，它是一个元组（例如 (10, 0) 表示 "10.0"）。如果指定了最低版本，后端还必须实现 DatabaseWrapper.get_database_version()，该方法返回当前数据库版本的元组。后端的 DatabaseWrapper.init_connection_state() 方法必须调用 super() 以便进行版本检查。

表单¶

渲染表单时默认使用的模板，例如在模板中作为 {{ form }} 显示，现在可以在项目级别通过在提供给 FORM_RENDERER 的类上设置 form_template_name 来配置。

Form.template_name 现在是一个属性，延迟到渲染器，但可以用一个字符串值覆盖，以指定每个表单类的模板名称。

同样，可以通过匹配的 formset_template_name 渲染器属性来指定用于渲染表单集的默认模板。
新的 div.html 表单模板引用了 Form.template_name_div 属性，并与 Form.as_div() 方法匹配，使用 HTML
元素来渲染表单。

推荐使用这种新的输出样式，而不是现有的 as_table()、as_p() 和 as_ul() 样式，因为模板实现了
和来组合相关的输入，对屏幕阅读器用户更容易导航。

从 Django 5.0 开始，基于 div 的输出将成为默认的渲染样式。
为了平稳过渡到新的
输出样式，提供了两个过渡性的表单渲染器类：django.forms.renderers.DjangoDivFormRenderer 和 django.forms.renderers.Jinja2DivFormRenderer，分别适用于 Django 和 Jinja2 模板后端。

您可以通过 FORM_RENDERER 设置之一来应用其中之一。例如：
```
FORM_RENDERER = "django.forms.renderers.DjangoDivFormRenderer"
```
一旦
输出样式成为默认样式（从 Django 5.0 开始），这些过渡渲染器将被弃用，并计划在 Django 6.0 中移除。届时可以删除 FORM_RENDERER 声明。
如果新的
输出样式不适用于您的项目，您应该定义一个渲染器子类，指定 form_template_name 和 formset_template_name 以适应您所需的样式，并相应地设置 FORM_RENDERER。

例如，对于 as_p() 使用的
输出样式，您可以定义一个表单渲染器设置，将 form_template_name 设置为 "django/forms/p.html"，将 formset_template_name 设置为 "django/forms/formsets/p.html"。
新的 legend_tag() 允许通过 label_tag() 的新 tag 参数以标签方式呈现字段标签。
对于 modelformset_factory() 和 inlineformset_factory()，新的 edit_only 参数允许防止创建新对象。
媒体的 js 和 css 类属性现在允许使用可散列的对象，而不仅仅是路径字符串，只要这些对象实现了 __html__() 方法（通常在使用 html_safe() 装饰器时）。
新的 BoundField.use_fieldset 和 Widget.use_fieldset 属性有助于识别那些应该在
中与一起分组的小部件。
BaseFormSet 的 error_messages 参数现在允许通过传递 'too_few_forms' 和 'too_many_forms' 键来自定义无效表单数量的错误消息。
IntegerField、FloatField 和 DecimalField 现在可以选择接受一个 step_size 参数。这用于设置 step HTML 属性，并在表单提交时进行验证。

国际化¶

i18n_patterns() 函数现在支持同时包含脚本和区域的语言。

管理命令¶

makemigrations --no-input 现在记录默认答案和无法创建迁移的原因。
新的 makemigrations --scriptable 选项将日志输出和输入提示重定向到 stderr，仅将生成的迁移文件的路径写入 stdout。
新的 migrate --prune 选项允许从 django_migrations 表中删除不存在的迁移。
由 startproject、startapp、optimizemigration、makemigrations 和 squashmigrations 创建的 Python 文件现在如果在您的 PATH 上存在 black 命令，将会使用它进行格式化。
新的 optimizemigration 命令允许优化迁移操作。

迁移¶

新的 RenameIndex 操作允许重命名在 Meta.indexes 或 index_together 选项中定义的索引。
迁移自动检测器现在在重命名 Meta.indexes 中定义的索引时，生成 RenameIndex 操作，而不是 RemoveIndex 和 AddIndex。
迁移自动检测器现在会在将 Meta.index_together 中定义的索引移动到 Meta.indexes 时生成 RenameIndex 操作，而不是 AlterIndexTogether 和 AddIndex。

模型¶

Window 表达式的 order_by 参数现在可以接受对字段和转换的字符串引用。
新的 CONN_HEALTH_CHECKS 设置允许启用对持久数据库连接进行健康检查，以减少失败的请求次数，例如在数据库服务器重新启动后。
现在，当插入一行时违反唯一约束时，QuerySet.bulk_create() 支持更新字段。这在 MariaDB、MySQL、PostgreSQL 和 SQLite 3.24+ 上都受支持。
QuerySet.iterator() 现在支持在提供了 chunk_size 参数的情况下预取相关对象。在旧版本中，不进行预取。
Q 对象和查询集现在可以使用 ^ 作为异或（XOR）运算符进行组合。XOR 在 MariaDB 和 MySQL 上有本地支持。对于不支持 XOR 的数据库，查询将被转换为使用 AND、OR 和 NOT 的等效查询。
新的 Field.non_db_attrs 属性允许自定义不影响列定义的字段属性。
在 PostgreSQL 上，AutoField、BigAutoField 和 SmallAutoField 现在作为标识列（identity columns）创建，而不是带有序列的序列列（serial columns）。

请求和响应¶

HttpResponse.set_cookie() 现在支持 timedelta 对象作为 max_age 参数。

安全¶

新的 SECRET_KEY_FALLBACKS 设置允许提供一组值用于密钥轮换。
SECURE_PROXY_SSL_HEADER 设置现在支持在头部值中以逗号分隔的协议列表。

信号¶

pre_delete 和 post_delete 信号现在会分发删除的 origin。

模板¶

在包装 json_script 模板过滤器时，不再需要 HTML 红百科豫ICP备13019747号-13