--- title: "Django 5.1 版本发行说明" version: 6.1 locale: zh-hans source: https://docs.djangoproject.com/zh-hans/6.1/releases/5.1/ canonical: https://djangodocs.dev/zh-hans/6.1/releases/5.1/ --- # Django 5.1 版本发行说明 *2024 年 8 月 7 日* 欢迎使用 Django 5.1！ 这些发布说明涵盖了 [新功能](#whats-new-5-1)，以及从 Django 5.0 或更早版本升级时应注意的一些 [不兼容的更改](#backwards-incompatible-5-1)。我们已经 [开始对一些功能进行弃用处理](#deprecated-features-5-1)。 如果你要更新现有的项目，请看 [如何将 Django 更新至新的版本](/zh-hans/6.1/howto/upgrade-version/) 指南。 ## Python 兼容性 Django 5.1 支持 Python 3.10、3.11、3.12 和 3.13（截至 5.1.3）。我们 **强烈建议** 并且仅官方支持每个系列的最新版本。 ## Django 5.1 新特性 ### `{% querystring %}` 模版标签 Django 5.1 引入了 [`{% querystring %}`](/zh-hans/6.1/ref/templates/builtins/#std-templatetag-querystring) 模板标签，简化了 URL 中查询参数的修改，使得生成在添加或更改特定参数的同时保持现有查询参数的链接变得更加容易。 例如，在模板中处理分页和查询字符串可能会很繁琐。考虑以下模板片段，它动态生成了一个用于在分页视图中导航到下一页的 URL： ```html+django {# Linebreaks added for readability, this should be one, long line. #} Next page ``` 当切换到使用这个新的模板标签时，上面的代码神奇地变成了： ```html+django Next page ``` ### PostgreSQL 连接池 Django 5.1 还引入了对 PostgreSQL 的 [连接池](/zh-hans/6.1/ref/databases/#postgresql-pool) 支持。由于建立新连接的时间可能相对较长，保持连接打开可以减少延迟。 要使用 [psycopg](https://www.psycopg.org/) 的连接池，你可以在 [`OPTIONS`](/zh-hans/6.1/ref/settings/#std-setting-OPTIONS) 中将 `"pool"` 选项设置为一个字典，传递给 [`ConnectionPool`](https://www.psycopg.org/psycopg3/docs/api/pool.html#psycopg_pool.ConnectionPool)，或者设置为 `True` 以使用 `ConnectionPool` 的默认值： ``` DATABASES = { "default": { "ENGINE": "django.db.backends.postgresql", # ... "OPTIONS": { "pool": { "min_size": 2, "max_size": 4, "timeout": 10, } }, }, } ``` ### 默认情况下需要身份验证的中间件 新的 [`LoginRequiredMiddleware`](/zh-hans/6.1/ref/middleware/#django.contrib.auth.middleware.LoginRequiredMiddleware) 将所有未经身份验证的请求重定向到登录页面。视图可以使用新的 [`login_not_required()`](/zh-hans/6.1/topics/auth/default/#django.contrib.auth.decorators.login_not_required) 装饰器来允许未经身份验证的请求。 `LoginRequiredMiddleware` 尊重通过 [`login_required()`](/zh-hans/6.1/topics/auth/default/#django.contrib.auth.decorators.login_required) 装饰器设置的 `login_url` 和 `redirect_field_name` 值，但不支持通过 [`LoginRequiredMixin`](/zh-hans/6.1/topics/auth/default/#django.contrib.auth.mixins.LoginRequiredMixin) 设置 `login_url` 或 `redirect_field_name`。 要启用此功能，请将 `"django.contrib.auth.middleware.LoginRequiredMiddleware"` 添加到你的 [`MIDDLEWARE`](/zh-hans/6.1/ref/settings/#std-setting-MIDDLEWARE) 设置中。 ### 次要特性 #### [`django.contrib.admin`](/zh-hans/6.1/ref/contrib/admin/#module-django.contrib.admin) - [`ModelAdmin.list_display`](/zh-hans/6.1/ref/contrib/admin/#django.contrib.admin.ModelAdmin.list_display) 现在支持使用 `__` 查找来列出相关模型的字段。 #### [`django.contrib.auth`](/zh-hans/6.1/topics/auth/#module-django.contrib.auth) - PBKDF2 密码哈希器的默认迭代次数从 720,000 增加到 870,000。 - `ScryptPasswordHasher` 的默认 `parallelism` 从 1 增加到 5，以遵循 OWASP 的建议。 - 新的 [`AdminUserCreationForm`](/zh-hans/6.1/topics/auth/default/#django.contrib.auth.forms.AdminUserCreationForm) 和现有的 [`AdminPasswordChangeForm`](/zh-hans/6.1/topics/auth/default/#django.contrib.auth.forms.AdminPasswordChangeForm) 现在支持通过在表单保存时设置不可用密码来禁用基于密码的身份验证。现在在访问用户创建和密码更改页面时，管理界面中也提供了此功能。 - [`login_required()`](/zh-hans/6.1/topics/auth/default/#django.contrib.auth.decorators.login_required)、[`permission_required()`](/zh-hans/6.1/topics/auth/default/#django.contrib.auth.decorators.permission_required) 和 [`user_passes_test()`](/zh-hans/6.1/topics/auth/default/#django.contrib.auth.decorators.user_passes_test) 装饰器现在支持包装异步视图函数。 - `ReadOnlyPasswordHashWidget` 现在包含一个重置用户密码的按钮，取代了之前嵌入在 `ReadOnlyPasswordHashField` 帮助文本中的链接，从而提高了 [`UserChangeForm`](/zh-hans/6.1/topics/auth/default/#django.contrib.auth.forms.UserChangeForm) 的整体可访问性。 #### [`django.contrib.gis`](/zh-hans/6.1/ref/contrib/gis/#module-django.contrib.gis) - [`BoundingCircle`](/zh-hans/6.1/ref/contrib/gis/functions/#django.contrib.gis.db.models.functions.BoundingCircle) 现在在 SpatiaLite 5.1+ 上受支持。 - [`Collect`](/zh-hans/6.1/ref/contrib/gis/geoquerysets/#django.contrib.gis.db.models.Collect) 现在在 MySQL 8.0.24+ 上受支持。 - [`GeoIP2`](/zh-hans/6.1/ref/contrib/gis/geoip2/#django.contrib.gis.geoip2.GeoIP2) 现在允许使用 [`ipaddress.IPv4Address`](https://docs.python.org/3/library/ipaddress.html#ipaddress.IPv4Address) 或 [`ipaddress.IPv6Address`](https://docs.python.org/3/library/ipaddress.html#ipaddress.IPv6Address) 对象进行查询。 - [`GeoIP2.country()`](/zh-hans/6.1/ref/contrib/gis/geoip2/#django.contrib.gis.geoip2.GeoIP2.country) 现在暴露了 `continent_code`、`continent_name` 和 `is_in_european_union` 值。 - [`GeoIP2.city()`](/zh-hans/6.1/ref/contrib/gis/geoip2/#django.contrib.gis.geoip2.GeoIP2.city) 现在暴露了 `accuracy_radius` 和 `region_name` 值。此外，`dma_code` 和 `region` 值现在分别暴露为 `metro_code` 和 `region_code`，但为了向后兼容，之前的键仍然保留。 - [`Area`](/zh-hans/6.1/ref/contrib/gis/measure/#django.contrib.gis.measure.Area) 现在支持 `ha` 单位。 - 新的 [`OGRGeometry.is_3d`](/zh-hans/6.1/ref/contrib/gis/gdal/#django.contrib.gis.gdal.OGRGeometry.is_3d) 属性允许检查几何体是否具有 `Z` 坐标维度。 - 新的 [`OGRGeometry.set_3d()`](/zh-hans/6.1/ref/contrib/gis/gdal/#django.contrib.gis.gdal.OGRGeometry.set_3d) 方法允许添加和移除 `Z` 坐标维度。 - [`OGRGeometry`](/zh-hans/6.1/ref/contrib/gis/gdal/#django.contrib.gis.gdal.OGRGeometry)、[`Point`](/zh-hans/6.1/ref/contrib/gis/gdal/#django.contrib.gis.gdal.Point)、[`LineString`](/zh-hans/6.1/ref/contrib/gis/gdal/#django.contrib.gis.gdal.LineString)、[`Polygon`](/zh-hans/6.1/ref/contrib/gis/gdal/#django.contrib.gis.gdal.Polygon) 和 [`GeometryCollection`](/zh-hans/6.1/ref/contrib/gis/gdal/#django.contrib.gis.gdal.GeometryCollection) 及其子类现在通过新的 [`OGRGeometry.is_measured`](/zh-hans/6.1/ref/contrib/gis/gdal/#django.contrib.gis.gdal.OGRGeometry.is_measured) 和 `m` 属性以及 [`OGRGeometry.set_measured()`](/zh-hans/6.1/ref/contrib/gis/gdal/#django.contrib.gis.gdal.OGRGeometry.set_measured) 方法支持测量几何体。 - [`OGRGeometry.centroid`](/zh-hans/6.1/ref/contrib/gis/gdal/#django.contrib.gis.gdal.OGRGeometry.centroid) 现在在所有支持的几何体类型上都可用。 - [`FromWKB()`](/zh-hans/6.1/ref/contrib/gis/functions/#django.contrib.gis.db.models.functions.FromWKB) 和 [`FromWKT()`](/zh-hans/6.1/ref/contrib/gis/functions/#django.contrib.gis.db.models.functions.FromWKT) 函数现在支持可选的 `srid` 参数（除了 Oracle，该参数被忽略）。 #### [`django.contrib.postgres`](/zh-hans/6.1/ref/contrib/postgres/#module-django.contrib.postgres) - [`BTreeIndex`](/zh-hans/6.1/ref/contrib/postgres/indexes/#django.contrib.postgres.indexes.BTreeIndex) 现在支持 `deduplicate_items` 参数。 #### [`django.contrib.sessions`](/zh-hans/6.1/topics/http/sessions/#module-django.contrib.sessions) - [`django.contrib.sessions.backends.cached_db.SessionStore`](/zh-hans/6.1/topics/http/sessions/#django.contrib.sessions.backends.cached_db.SessionStore) 现在处理在缓存中存储会话信息时的异常，通过新添加的 [sessions logger](/zh-hans/6.1/ref/logging/#django-contrib-sessions-logger) 记录适当的错误信息及其回溯。 - [`django.contrib.sessions.backends.base.SessionBase`](/zh-hans/6.1/topics/http/sessions/#django.contrib.sessions.backends.base.SessionBase) 和所有内置的会话引擎现在提供了异步 API。新的异步方法都以 `a` 前缀命名，例如 `aget()`、`akeys()` 或 `acycle_key()`。 #### 数据库后端 - `"init_command"` 选项现在在 SQLite 的 [`OPTIONS`](/zh-hans/6.1/ref/settings/#std-setting-OPTIONS) 中受支持，允许指定在连接时设置的 [pragma options](/zh-hans/6.1/ref/databases/#sqlite-init-command)。 - `"transaction_mode"` 选项现在在 SQLite 的 [`OPTIONS`](/zh-hans/6.1/ref/settings/#std-setting-OPTIONS) 中受支持，允许指定 [事务行为](/zh-hans/6.1/ref/databases/#sqlite-transaction-behavior)。 - `"pool"` 选项现在在 PostgreSQL 的 [`OPTIONS`](/zh-hans/6.1/ref/settings/#std-setting-OPTIONS) 中受支持，允许使用 [connection pools](/zh-hans/6.1/ref/databases/#postgresql-pool)。 #### 错误报告 - 为了提高可访问性，技术性的 404 和 500 错误页面现在对页眉、页脚和主要内容区域使用 HTML 地标元素。 #### 文件存储 - [`FileSystemStorage`](/zh-hans/6.1/ref/files/storage/#django.core.files.storage.FileSystemStorage) 的 [`allow_overwrite`](/zh-hans/6.1/ref/files/storage/#django.core.files.storage.FileSystemStorage.allow_overwrite) 参数现在允许将新文件保存到现有文件上。 #### 表单 - 为了提高可访问性并使屏幕阅读器能够将字段集与其帮助文本关联起来，表单字段集现在包含 `aria-describedby` HTML 属性。 #### 管理命令 - [`makemigrations`](/zh-hans/6.1/ref/django-admin/#django-admin-makemigrations) 命令现在为每个操作显示有意义的符号，以突出显示 [`操作类别`](/zh-hans/6.1/ref/migration-operations/#django.db.migrations.operations.base.OperationCategory)。 #### 迁移 - 新的 `Operation.category` 属性允许指定 [`makemigrations`](/zh-hans/6.1/ref/django-admin/#django-admin-makemigrations) 使用的 [`操作类别`](/zh-hans/6.1/ref/migration-operations/#django.db.migrations.operations.base.OperationCategory)，以便为操作显示有意义的符号。 #### 模型 - [`QuerySet.explain()`](/zh-hans/6.1/ref/models/querysets/#django.db.models.query.QuerySet.explain) 现在在 PostgreSQL 16+ 上支持 `generic_plan` 选项。 - [`RowRange`](/zh-hans/6.1/ref/models/expressions/#django.db.models.expressions.RowRange) 现在接受 `start` 参数的正整数和 `end` 参数的负整数。 - [`RowRange`](/zh-hans/6.1/ref/models/expressions/#django.db.models.expressions.RowRange) 和 [`ValueRange`](/zh-hans/6.1/ref/models/expressions/#django.db.models.expressions.ValueRange) 的新 `exclusion` 参数允许从窗口框架中排除行、组和并列项。 - [`QuerySet.order_by()`](/zh-hans/6.1/ref/models/querysets/#django.db.models.query.QuerySet.order_by) 现在支持通过注解转换（如 `JSONObject` 键和 `ArrayAgg` 索引）进行排序。 - 输出 [`CharField`](/zh-hans/6.1/ref/models/fields/#django.db.models.CharField)、[`EmailField`](/zh-hans/6.1/ref/models/fields/#django.db.models.EmailField)、[`SlugField`](/zh-hans/6.1/ref/models/fields/#django.db.models.SlugField)、[`URLField`](/zh-hans/6.1/ref/models/fields/#django.db.models.URLField)、[`TextField`](/zh-hans/6.1/ref/models/fields/#django.db.models.TextField) 或 [`ArrayField`](/zh-hans/6.1/ref/contrib/postgres/fields/#django.contrib.postgres.fields.ArrayField) 的 [`F()`](/zh-hans/6.1/ref/models/expressions/#django.db.models.F) 和 [`OuterRef()`](/zh-hans/6.1/ref/models/expressions/#django.db.models.OuterRef) 表达式现在可以 [切片](/zh-hans/6.1/ref/models/expressions/#slicing-using-f)。 - [`Model.refresh_from_db()`](/zh-hans/6.1/ref/models/instances/#django.db.models.Model.refresh_from_db) 和 [`Model.arefresh_from_db()`](/zh-hans/6.1/ref/models/instances/#django.db.models.Model.arefresh_from_db) 的新 `from_queryset` 参数允许自定义用于重新加载模型值的查询集。这可以用于在重新加载之前锁定行或选择相关对象。 - 新的 [`Expression.constraint_validation_compatible`](/zh-hans/6.1/ref/models/expressions/#django.db.models.Expression.constraint_validation_compatible) 属性允许指定在约束验证期间忽略该表达式。 #### 模板 - 自定义标签现在可以在 `Parser` 对象上设置额外的数据，这些数据稍后将在 `Template` 实例上可用。例如，模板加载器或其他模板客户端可以使用这些数据。 - [模板引擎](/zh-hans/6.1/topics/checks/#field-checking) 现在实现了一个 `check()` 方法，该方法已经注册到检查框架中。 #### 测试 - [`assertContains()`](/zh-hans/6.1/topics/testing/tools/#django.test.SimpleTestCase.assertContains)、[`assertNotContains()`](/zh-hans/6.1/topics/testing/tools/#django.test.SimpleTestCase.assertNotContains) 和 [`assertInHTML()`](/zh-hans/6.1/topics/testing/tools/#django.test.SimpleTestCase.assertInHTML) 断言现在将干草堆添加到断言错误消息中。 - [`RequestFactory`](/zh-hans/6.1/topics/testing/advanced/#django.test.RequestFactory)、[`AsyncRequestFactory`](/zh-hans/6.1/topics/testing/advanced/#django.test.AsyncRequestFactory)、[`Client`](/zh-hans/6.1/topics/testing/tools/#django.test.Client) 和 [`AsyncClient`](/zh-hans/6.1/topics/testing/tools/#django.test.AsyncClient) 类现在支持 `query_params` 参数，该参数接受查询字符串键和值的字典。这使得在任何 HTTP 方法上设置查询字符串变得更加容易。 ```python self.client.post("/items/1", query_params={"action": "delete"}) await self.async_client.post("/items/1", query_params={"action": "delete"}) ``` - 新的 [`SimpleTestCase.assertNotInHTML()`](/zh-hans/6.1/topics/testing/tools/#django.test.SimpleTestCase.assertNotInHTML) 断言允许测试给定的 HTML 干草堆中不包含某个 HTML 片段。 - 为了强制测试隔离，[`SimpleTestCase`](/zh-hans/6.1/topics/testing/tools/#django.test.SimpleTestCase) 中不再允许在线程内使用数据库连接。 #### 验证器 - 新的 [`DomainNameValidator`](/zh-hans/6.1/ref/validators/#django.core.validators.DomainNameValidator) 验证域名，包括国际化域名。新的 [`validate_domain_name()`](/zh-hans/6.1/ref/validators/#django.core.validators.validate_domain_name) 函数返回 [`DomainNameValidator`](/zh-hans/6.1/ref/validators/#django.core.validators.DomainNameValidator) 的实例。 ## 5.1 版本中不向后兼容的变更 ### [`django.contrib.gis`](/zh-hans/6.1/ref/contrib/gis/#module-django.contrib.gis) - 移除对 PostGIS 2.5 的支持。 - 已移除对 `PROJ` 版本低于 6 的支持。 - 移除对 GDAL 2.4 的支持。 - [`GeoIP2`](/zh-hans/6.1/ref/contrib/gis/geoip2/#django.contrib.gis.geoip2.GeoIP2) 在提供目录路径时不再同时打开城市和国家数据库，而是优先使用城市数据库（如果可用）。国家数据库是城市数据库的子集，通常不需要同时使用两者。如果你需要在与城市数据库相同的目录中使用国家数据库，请显式地将国家数据库路径传递给构造函数。 ### 不再支持 MariaDB 10.4 上游对 MariaDB 10.4 的支持将于 2024 年 6 月结束。Django 5.1 支持 MariaDB 10.5 及更高版本。 ### 不再支持 PostgreSQL 12 上游对 PostgreSQL 12 的支持将于 2024 年 11 月结束。Django 5.1 支持 PostgreSQL 13 及更高版本。 ### 杂项 - 为了提高可访问性，管理界面的变更列表过滤器现在在 `