配置

配置

核心配置
认证
消息
会话
站点
静态文件
核心配置专题索引

警告

当你覆盖配置时要小心，特别是当默认值是一个非空的列表或字典时，如 STATICFILES_FINDERS。确保你保留了你希望使用的 Django 功能所需要的组件。

核心配置

下面是 Django 核心中可用的配置及其默认值的列表。下面列出了 contrib 应用提供的设置，后面是核心配置的专题索引。关于介绍性资料，请看配置专题指南。

`ABSOLUTE_URL_OVERRIDES`

默认： {} （空字典）

将 "app_label.model_name" 字符串映射到接受模型对象并返回其 URL 的函数的字典。这是一种在每个预安装基础上插入或覆盖 get_absolute_url() 方法的方式。例如：

ABSOLUTE_URL_OVERRIDES = {
    "blogs.blog": lambda o: "/blogs/%s/" % o.slug,
    "news.story": lambda o: "/stories/%s/%s/" % (o.pub_year, o.slug),
}

在此配置中使用的模型名称应全部为小写，与实际模型类名称的大小写无关。

`ADMINS`

默认： [] （空列表）

所有收到代码错误通知的人的列表。当 DEBUG=False 和 AdminEmailHandler 中设置了 LOGGING 时（默认情况下是这样做的），Django 会将请求／响应周期中出现的异常的详细信息通过邮件发送给这些人。

列表中的每个项目应该是一个元组 (全名, 电子邮件地址)。例如：

[("John", "john@example.com"), ("Mary", "mary@example.com")]

`ALLOWED_HOSTS`

默认： [] （空列表）

一个代表这个 Django 网站可以服务的主机／域名的字符串列表。这是一个安全措施，以防止 HTTP 主机头攻击，即使在许多看似安全的 Web 服务器配置下也有可能发生。

这个列表中的值可以是完全限定的名称（例如 'www.example.com），在这种情况下，它们将与请求的 Host 头完全匹配（不区分大小写，不包括端口）。以英文句号开头的值可以用作子域通配符。'.example.com' 将匹配 example.com、www.example.com 和 example.com 的任何其他子域。'*' 的值将匹配任何东西；在这种情况下，你要负责提供你自己的 Host 头的验证（也许是在一个中间件中；如果是这样，这个中间件必须首先在 MIDDLEWARE 中列出）。

Django 也允许在任何条目中使用完全合格的域名（FQDN）。有些浏览器在 Host 头中包含了一个尾部的点，Django 在执行主机验证时将其去掉。

如果 Host 头（或者 X-Forwarded-Host 如果 USE_X_FORWARDED_HOST 被启用的话）不符合这个列表中的任何值，则 django.http.HttpRequest.get_host() 方法将引发 SuspiciousOperation。

当 DEBUG`为``True` 和 ALLOWED_HOSTS 为空时，主机将根据 ['.localhost', '127.0.0.1', '[::1]'] 进行验证。

ALLOWED_HOSTS 也是在运行测试时进行检查的。

这些验证仅通过 get_host() 来实现；如果你的代码直接从 request.META 得到 Host 头部，你就绕过了这种安全保护机制。

`APPEND_SLASH`

默认： True

当设置为 True 时，如果请求的 URL 不符合 URLconf 中的任何模式，并且不以斜线结尾，则会发出一个 HTTP 重定向到相同的URL，并附加一个斜线。注意，重定向可能会导致 POST 请求中提交的任何数据丢失。

APPEND_SLASH 的配置只有在安装了 CommonMiddleware 的情况下才会使用（参见中间件）。也请参见 PREPEND_WWW。

`CACHES`

默认：

{
    "default": {
        "BACKEND": "django.core.cache.backends.locmem.LocMemCache",
    }
}

一个包含所有 Django 缓存配置的字典。它是一个嵌套的字典，其内容将缓存别名映射到一个包含单个缓存选项的字典中。

CACHES 配置必须设置一个 default 缓存；也可以指定任何数量的附加缓存。如果你使用的是本地内存缓存以外的缓存后端，或者你需要定义多个缓存，则需要其他选项。以下是可用的缓存选项。

`BACKEND`

默认： '' （空字符串）

要使用的缓存后端。内置的缓存后端有：

'django.core.cache.backends.db.DatabaseCache'
'django.core.cache.backends.dummy.DummyCache'
'django.core.cache.backends.filebased.FileBasedCache'
'django.core.cache.backends.locmem.LocMemCache'
'django.core.cache.backends.memcached.PyMemcacheCache'
'django.core.cache.backends.memcached.PyLibMCCache'
'django.core.cache.backends.redis.RedisCache'

你可以通过将 :set:`BACKEND <CACHES-BACKEND>` 设置为一个完全限定的缓存后端类的路径（例如 mypackage.backends.whatever.WhateverCache），来使用一个不在 Django 中的缓存后端。

`KEY_FUNCTION`

一个字符串，包含一个指向函数（或任何可调用）的点分隔路径，定义如何将前缀、版本和密钥组成一个最终的缓存密钥。默认的实现相当于函数：

def make_key(key, key_prefix, version):
    return ":".join([key_prefix, str(version), key])

你可以使用任何你想要的密钥函数，只要它有相同的参数签名。

查看缓存文档获取更多信息。

`KEY_PREFIX`

默认： '' （空字符串）

一个自动包含在 Django 服务器使用的所有缓存键中的字符串（默认情况下是前缀）。

查看缓存文档获取更多信息。

`LOCATION`

默认： '' （空字符串）

要使用的高速缓存的位置。可能是文件系统缓存的目录，memcache 服务器的主机和端口，或者是本地内存缓存的识别名称，例如：

CACHES = {
    "default": {
        "BACKEND": "django.core.cache.backends.filebased.FileBasedCache",
        "LOCATION": "/var/tmp/django_cache",
    }
}

`OPTIONS`

默认： None

传递给缓存后端的额外参数。可用的参数根据你的缓存后端不同而不同。

关于可用参数的一些信息可以在缓存参数文档中找到。更多信息，请查阅你的后端模块自己的文档。

`TIMEOUT`

默认： 300

缓存条目被视为过期之前的秒数。如果此设置的值为 None，则缓存条目不会过期。值为 0 会导致键立即过期（实际上是”不缓存”）。

`VERSION`

默认： 1

Django 服务器生成的缓存密钥的默认版本号。

查看缓存文档获取更多信息。

`CACHE_MIDDLEWARE_ALIAS`

默认： 'default'

用于缓存中间件的缓存连接。

`CACHE_MIDDLEWARE_KEY_PREFIX`

默认： '' （空字符串）

由缓存中间件生成的缓存密钥前缀的字符串。这个前缀与 KEY_PREFIX 的配置结合在一起，而不是取代它。

参见 Django 缓存框架。

`CACHE_MIDDLEWARE_SECONDS`

默认： 600

默认为缓存中间件缓存页面的秒数。

参见 Django 缓存框架。

`CSRF_COOKIE_AGE`

默认： 31449600 （约 1 年，以秒为单位）

CSRF cookie 的寿命，以秒为单位。

设置长效过期时间的原因是为了避免在用户关闭浏览器或将某一页面作为书签，然后从浏览器缓存中加载该页面时出现问题。如果没有持久性 Cookie，这种情况下表单提交会失败。

一些浏览器（特别是 Internet Explorer）可能不允许使用持久性 cookie，或可能使 cookie jar 的索引在磁盘上损坏，从而导致 CSRF 保护检查（有时是间歇性的）失败。将此设置改为 None，以使用基于会话的 CSRF cookie，它将 cookie 保存在内存中，而不是持久性存储中。

`CSRF_COOKIE_DOMAIN`

默认： None

设置 CSRF cookie 时要使用的域。这对于允许跨子域请求被排除在正常的跨站点请求伪造保护之外是很有用的。它应该设置为一个字符串，如 ".example.com"，以允许一个子域上的表单的 POST 请求被另一个子域的视图所接受。

请注意，这个配置的存在并不意味着 Django 的 CSRF 保护在默认情况下是安全的，不会受到跨子域的攻击——请参见 CSRF 限制部分。

`CSRF_COOKIE_HTTPONLY`

默认：False

是否对 CSRF cookie 使用 HttpOnly 标志。如果设置为 True，客户端的 JavaScript 将无法访问 CSRF cookie。

将 CSRF cookie 指定为 HttpOnly 并不能提供任何实际的保护，因为 CSRF 只是为了防止跨域攻击。如果攻击者可以通过 JavaScript 读取 cookie，就浏览器所知，他们已经在同一个域上了，所以他们可以做任何他们喜欢的事情。（XSS 是一个比 CSRF 更大的漏洞）。

虽然这种配置没有提供什么实际的好处，但有时也会被安全审计人员要求。

如果你启用了这个功能，并且需要通过 AJAX 请求发送 CSRF 标记的值，你的 JavaScript 必须从隐藏的 CSRF 标记表单输入中提取值而不是从 cookie。

关于 HttpOnly 的详细信息，请参见 SESSION_COOKIE_HTTPONLY。

`CSRF_COOKIE_MASKED`

New in Django 4.1.

默认：False

是否对 CSRF cookie 进行掩码处理。有关使用详细信息，请参阅发布说明。

4.1 版后已移除: 这个过渡性设置已被弃用，并将在 Django 5.0 中删除。

`CSRF_COOKIE_NAME`

默认： 'csrftoken'

用于 CSRF 认证令牌的 cookie 的名称。这可以是任何你想要的名字（只要它与你的应用程序中的其他 cookie 名字不同）。参见跨站请求伪造保护。

`CSRF_COOKIE_PATH`

默认： '/'

在 CSRF cookie 上设置的路径。这个路径应该与你的 Django 安装的 URL 路径相匹配，或者是该路径的父路径。

如果你有多个 Django 实例在同一个主机名下运行，这个功能很有用。他们可以使用不同的 cookie 路径，而且每个实例只能看到自己的 CSRF cookie。

`CSRF_COOKIE_SAMESITE`

默认： 'Lax'

CSRF cookie 上 SameSite 标志的值。该标志可防止在跨站点请求中发送 cookie。

关于 SameSite 的详细信息，请参见 SESSION_COOKIE_SAMESITE。

`CSRF_COOKIE_SECURE`

默认：False

是否为 CSRF cookie 使用安全 cookie。如果设置为 True，cookie 将被标记为 安全，这意味着浏览器可以确保 cookie 只在 HTTPS 连接下发送。

`CSRF_USE_SESSIONS`

默认：False

是否将 CSRF 标记存储在用户的会话中，而不是 cookie 中。这需要使用 django.contrib.session。

将 CSRF 令牌存储在 cookie 中（Django 的默认值）是安全的，但将其存储在 session 中是其他 Web 框架的常见做法，因此有时会被安全审计人员要求。

由于默认错误视图需要CSRF令牌，所以 SessionMiddleware 必须出现在 MIDDLEWARE 中，在任何可能引发异常以触发错误视图的中间件（如 PermissionDenied）之前，如果你正在使用 CSRF_USE_SESSIONS。参见中间件顺序。

`CSRF_FAILURE_VIEW`

默认： 'django.views.csrf.csrf_failure'

当传入的请求被 CSRF 保护拒绝时，要使用的视图函数的点分隔路径。该函数应具有以下签名：

def csrf_failure(request, reason=""):
    ...

其中 reason 是一个简短的消息（针对开发者或日志记录，而不是针对终端用户），表示请求被拒绝的原因，它应该返回一个 HttpResponseForbidden。

django.views.csrf.csrf_failure() 接受一个额外的 template_name 参数，默认为 '403_csrf.html'。如果存在该名称的模板，它将被用来渲染页面。

`CSRF_HEADER_NAME`

默认： 'HTTP_X_CSRFTOKEN'

用于 CSRF 认证的请求头的名称。

与 request.META 中的其他 HTTP 头文件一样，从服务器接收到的头文件名通过将所有字符转换为大写字母，用下划线代替任何连字符，并在名称中添加 'HTTP_' 前缀进行规范化。例如，如果你的客户端发送了一个 'X-XSRF-TOKEN' 头，配置应该是 'HTTP_X_XSRF_TOKEN'。

`CSRF_TRUSTED_ORIGINS`

默认： [] （空列表）

一组信任的来源，用于不安全的请求（例如 POST）。

对于包含 Origin 头的请求，Django 的 CSRF 保护要求该头部与 Host 头中的来源匹配。

对于不包含 Origin 头的 secure 不安全请求，请求必须具有与 Host 头中的来源匹配的 Referer 头。

这些检查可以防止，例如，来自 subdomain.example.com 的 POST 请求成功访问 api.example.com。如果你需要跨域不安全请求，继续上面的示例，在此列表中添加 'https://subdomain.example.com' （如果请求来自不安全页面，也可以添加 http://...）。

这个设置也支持子域名，因此你可以添加 'https://*.example.com'，例如，以允许来自 example.com 的所有子域名的访问。

`DATABASES`

默认： {} （空字典）

一个包含所有数据库配置的字典，用于 Django。它是一个嵌套的字典，其内容是将一个数据库别名映射到一个包含单个数据库选项的字典中。

DATABASES 配置必须设置一个 default 数据库；也可以指定任何数量的其他数据库。

最简单的配置文件是使用 SQLite 的单数据库配置。可以通过以下方式进行配置：

DATABASES = {
    "default": {
        "ENGINE": "django.db.backends.sqlite3",
        "NAME": "mydatabase",
    }
}

当连接到其他数据库后端时，如 MariaDB、MySQL、Oracle 或 PostgreSQL，将需要额外的连接参数。请参阅下面的 ENGINE 配置，了解如何指定其他数据库类型。这个例子是针对 PostgreSQL：

DATABASES = {
    "default": {
        "ENGINE": "django.db.backends.postgresql",
        "NAME": "mydatabase",
        "USER": "mydatabaseuser",
        "PASSWORD": "mypassword",
        "HOST": "127.0.0.1",
        "PORT": "5432",
    }
}

以下是更复杂配置可能需要的内部选项：

`ATOMIC_REQUESTS`

默认：False

将此设置为 True，以将每个视图包裹在这个数据库的事务中。参见连结事务与 HTTP 请求。

`AUTOCOMMIT`

默认： True

如果你想禁用 Django 的事务管理并实现你自己的事务管理，请将此设置为 False。

`ENGINE`

默认： '' （空字符串）

要使用的数据库后端。内置的数据库后端有：

'django.db.backends.postgresql'
'django.db.backends.mysql'
'django.db.backends.sqlite3'
'django.db.backends.oracle'

你可以通过将 ENGINE 设置为一个完全限定的路径（例如： mypackage.backends.whatever），来使用一个不在 Django 中的数据库后端。

`HOST`

默认： '' （空字符串）

连接到数据库时使用的主机。空字符串表示本地主机。不用于 SQLite。

如果这个值以斜线（'/'）开头，并且你正在使用 MySQL，MySQL 将通过 Unix 套接字连接到指定的套接字。例如：

"HOST": "/var/run/mysql"

如果你使用的是 MySQL，并且这个值没有以斜线开头，那么这个值被认为是主机。

如果你使用的是 PostgreSQL，默认情况下（空 HOST），与数据库的连接是通过 UNIX 域套接字（pg_hba.conf 中的 ‘local’ ）完成的。如果你的 UNIX 域套接字不在标准位置，请使用 postgresql.conf 中的 unix_socket_directory 的相同值。如果你想通过 TCP 套接字连接，将 HOST 设置为 ‘localhost’ 或 ‘127.0.0.1’（pg_hba.conf 中的 ‘host’ 行）。在 Windows 上，你应该总是定义 HOST，因为 UNIX 域套接字是不可用的。

`NAME`

默认： '' （空字符串）

要使用的数据库的名称。对于 SQLite，它是数据库文件的完整路径。当指定路径时，总是使用斜线，即使在 Windows 上也是如此（例如 C:/homes/user/mysite/sqlite3.db）。

`CONN_MAX_AGE`

默认： 0

数据库连接的生命周期，以秒为单位的整数。使用 0 来在每个请求结束时关闭数据库连接（Django 的历史行为），使用 None 来表示无限的持久数据库连接。

`CONN_HEALTH_CHECKS`

New in Django 4.1.

默认：False

如果设置为 True，在每个执行数据库访问的请求中重用现有的持久数据库连接之前，将对它们进行健康检查。如果健康检查失败，当连接不再可用但数据库服务器已准备好接受和提供新连接时（例如，在数据库服务器重新启动并关闭现有连接后），将重新建立连接，而不会导致请求失败。

`OPTIONS`

默认： {} （空字典）

连接到数据库时要使用的额外参数。可用的参数根据你的数据库后端不同而不同。

关于可用参数的一些信息可以在数据库后端文档中找到。更多信息，请查阅你的后端模块自己的文档。

`PASSWORD`

默认： '' （空字符串）

连接到数据库时使用的密码。不用于 SQLite。

`PORT`

默认： '' （空字符串）

连接到数据库时要使用的端口。空字符串表示默认端口。不用于 SQLite。

`TIME_ZONE`

默认： None

代表该数据库连接时区的字符串或 None。DATABASES 配置的这个内部选项与一般的 TIME_ZONE 配置接受相同的值。

当 USE_TZ 为 True 且设置了这个选项时，从数据库中读取日期时间会返回这个时区的感知日期时间，而不是 UTC。当 USE_TZ 为 False 时，设置该选项是错误的。

如果数据库后端不支持时区（如 SQLite、MySQL、Oracle），如果设置了这个选项，Django 会根据这个选项以当地时间读写日期，如果没有设置，则以 UTC 时间读写。

改变连接时区会改变从数据库中读取和写入日期的方式。
- 如果 Django 管理数据库，并且没有强烈的理由进行更改，最好将此选项保持未设置。最好将日期时间存储为 UTC，因为这可以避免在夏令时变化期间出现模糊或不存在的日期时间。另外，接收 UTC 日期时间可以保持日期时间算术的简单性 — 不需要考虑夏令时转换期间潜在的偏移更改。
- 如果你连接的第三方数据库以当地时间而不是 UTC 存储日期，那么你必须将这个选项设置为合适的时区。同样，如果 Django 管理数据库，但第三方系统连接到同一个数据库，并希望找到当地时间的日期，那么你必须设置这个选项。
如果数据库后端支持时区（如 PostgreSQL），很少需要 TIME_ZONE 选项。它可以在任何时候改变；数据库会负责将日期时间转换为所需的时区。

设置数据库连接的时区对于运行涉及数据库提供的日期／时间函数的原始 SQL 查询（如 date_trunc）可能很有用，因为其结果取决于时区。

然而，这也有一个缺点：接收所有日期时间都以本地时间表示会使日期时间运算变得更加复杂 — 你必须考虑夏令时转换期间可能发生的偏移变化。

考虑在原始 SQL 查询中使用 AT TIME ZONE 明确转换为当地时间，而不是设置 TIME_ZONE 选项。

`DISABLE_SERVER_SIDE_CURSORS`

默认：False

如果你想通过 QuerySet.iterator() 禁用服务器端游标的使用，请将其设置为 True。事务池和服务器端游标描述了使用情况。

这是 PostgreSQL 特有的配置。

`USER`

默认： '' （空字符串）

连接数据库时要使用的用户名。不用于 SQLite。

`TEST`

默认： {} （空字典）

测试数据库的设置字典；关于测试数据库的创建和使用的更多细节，见测试数据库。

下面是一个测试数据库配置的例子：

DATABASES = {
    "default": {
        "ENGINE": "django.db.backends.postgresql",
        "USER": "mydatabaseuser",
        "NAME": "mydatabase",
        "TEST": {
            "NAME": "mytestdatabase",
        },
    },
}

TEST 字典中的下列键可供使用：

`CHARSET`

默认： None

用于创建测试数据库的字符集编码。这个字符串的值是直接传递给数据库的，所以它的格式是特定于后端的。

由 PostgreSQL （postgresql）和 MySQL （mysql）后端支持。

`COLLATION`

默认： None

创建测试数据库时要使用的字符序。这个值是直接传递给后端的，所以它的格式是后端特定的。

仅支持 mysql 后端（详见 MySQL 手册）。

`DEPENDENCIES`

默认：['default']，适用于除 default 以外的所有数据库，后者没有依赖性。

数据库的创建顺序依赖性。详见控制测试数据库的创建顺序的文档。

`MIGRATE`

默认： True

当设置为 False 时，在创建测试数据库时不会运行迁移。这类似于在 MIGRATION_MODULES 中设置 None 作为一个值，但适用于所有应用程序。

`MIRROR`

默认： None

这个数据库应该在测试期间进行镜像的数据库的别名。它依赖于事务，因此必须在 TransactionTestCase 而不是 TestCase 中使用。

该配置允许测试多个数据库的主／副本（某些数据库称为主／从）配置。详情请参见测试主／副本配置的文档。

`NAME`

默认： None

运行测试套件时要使用的数据库名称。

如果 SQLite 数据库引擎使用默认值（None），则测试将使用内存常驻数据库。对于所有其他数据库引擎，测试数据库将使用 'test_' + DATABASE_NAME 的名称。

查看测试数据库。

`SERIALIZE`

布尔值，用于控制默认的测试运行器是否在运行测试之前将数据库序列化为内存中的 JSON 字符串（如果没有事务，用于在测试之间恢复数据库状态）。如果你没有任何带有 serialized_rollback=True 的测试类，你可以将其设置为 False 以加快创建时间。

4.0 版后已移除: 这个设置已被弃用，因为它可以从启用 serialized_rollback 选项的 databases 推断出来。

默认： '25M'

这是 Oracle 特有的配置。

当需要更多空间时，DATAFILE_TMP 的扩展量。

`DATA_UPLOAD_MAX_MEMORY_SIZE`

默认： 2621440 （即 2.5 MB）。

请求体在引发 SuspiciousOperation （RequestDataTooBig）之前的最大字节数。这个检查是在访问 request.body 或 request.POST 时进行的，是根据请求的总大小计算的，不包括任何文件上传数据。你可以将其设置为 None 以禁用该检查。预计会收到非常大的上传表单的应用程序应该调整这个配置。

请求数据的数量与处理请求和填充 GET 和 POST 字典所需的内存量相关。如果不进行检查，大的请求可能会被用作拒绝服务的攻击载体。由于 Web 服务器通常不会进行深层的请求检查，所以不可能在这个层面进行类似的检查。

另见 FILE_UPLOAD_MAX_MEMORY_SIZE。

`DATA_UPLOAD_MAX_NUMBER_FIELDS`

默认： 1000

在发生 SuspiciousOperation （TooManyFields）之前，可以通过 GET 或 POST 接收到的参数的最大数量。你可以将其设置为 None 来禁用该检查。预计会收到异常多的表单字段的应用程序应该调整这个配置。

请求参数的数量与处理请求和填充 GET 和 POST 字典所需的时间有关。如果不加以检查，大的请求可能会被用作拒绝服务攻击的载体。由于 Web 服务器通常不会进行深层的请求检查，所以不可能在这个层面进行类似的检查。

`DATA_UPLOAD_MAX_NUMBER_FILES`

New in Django 3.2.18.

默认： 100

在使用 multipart/form-data 编码的请求中，可以通过 POST 接收的文件的最大数量，在引发 SuspiciousOperation （TooManyFiles）之前。你可以将其设置为 None 以禁用此检查。预计会接收到异常多的文件字段的应用程序应调整此设置。

接受的文件数量与处理请求所需的时间和内存量相关联。如果不加以检查，大型请求可能会被用作拒绝服务攻击的矢量。由于 Web 服务器通常不执行深度请求检查，因此在该级别不可能执行类似的检查。

`DATABASE_ROUTERS`

默认： [] （空列表）

在执行数据库查询时，将用于确定使用哪个数据库的路由器列表。

参见多数据库配置中的自动数据库路由的文档。

`DATE_FORMAT`

默认： 'N j, Y' （例如 Feb. 4, 2003）

在系统的任何部分显示日期字段时使用的默认格式。请注意，如果 USE_L10N 被设置为 True，那么本地决定的格式具有更高的优先权，并将被应用。参见允许的日期格式字符串。

另见 DATETIME_FORMAT、TIME_FORMAT 和 SHORT_DATE_FORMAT。

`DATE_INPUT_FORMATS`

默认：

[
    "%Y-%m-%d",  # '2006-10-25'
    "%m/%d/%Y",  # '10/25/2006'
    "%m/%d/%y",  # '10/25/06'
    "%b %d %Y",  # 'Oct 25 2006'
    "%b %d, %Y",  # 'Oct 25, 2006'
    "%d %b %Y",  # '25 Oct 2006'
    "%d %b, %Y",  # '25 Oct, 2006'
    "%B %d %Y",  # 'October 25 2006'
    "%B %d, %Y",  # 'October 25, 2006'
    "%d %B %Y",  # '25 October 2006'
    "%d %B, %Y",  # '25 October, 2006'
]

在日期字段上输入数据时接受的格式列表。格式将按顺序被尝试，使用第一个有效的格式。注意这些格式字符串使用 Python 的 datetime 模块语法，而不是来自 date 模板过滤器的格式字符串。

当 USE_L10N 为 True 时，将采用本地规定的格式，具有更高的优先权。

另见 DATETIME_INPUT_FORMATS 和 TIME_INPUT_FORMATS。

`DATETIME_FORMAT`

默认： 'N j, Y, P' （例如 Feb. 4, 2003, 4 p.m.）

在系统的任何部分显示日期时间字段时使用的默认格式。请注意，如果 USE_L10N 被设置为 True，那么本地决定的格式具有更高的优先权，并将被应用。参见允许的日期格式字符串。

另见 DATE_FORMAT、TIME_FORMAT 和 SHORT_DATETIME_FORMAT。

`DATETIME_INPUT_FORMATS`

默认：

[
    "%Y-%m-%d %H:%M:%S",  # '2006-10-25 14:30:59'
    "%Y-%m-%d %H:%M:%S.%f",  # '2006-10-25 14:30:59.000200'
    "%Y-%m-%d %H:%M",  # '2006-10-25 14:30'
    "%m/%d/%Y %H:%M:%S",  # '10/25/2006 14:30:59'
    "%m/%d/%Y %H:%M:%S.%f",  # '10/25/2006 14:30:59.000200'
    "%m/%d/%Y %H:%M",  # '10/25/2006 14:30'
    "%m/%d/%y %H:%M:%S",  # '10/25/06 14:30:59'
    "%m/%d/%y %H:%M:%S.%f",  # '10/25/06 14:30:59.000200'
    "%m/%d/%y %H:%M",  # '10/25/06 14:30'
]

在日期时间字段上输入数据时可接受的格式列表。格式将按顺序被尝试，使用第一个有效的格式。注意这些格式字符串使用 Python 的 datetime 模块语法，而不是 date 模板过滤器的格式字符串。纯日期格式不包括在内，因为日期时间字段会在最后时刻自动尝试 DATE_INPUT_FORMATS。

当 USE_L10N 为 True 时，将采用本地规定的格式，具有更高的优先权。

另见 DATE_INPUT_FORMATS 和 TIME_INPUT_FORMATS。

`DEBUG`

默认：False

一个开启、关闭调试模式的布尔值。

永远不要在 DEBUG 开启的情况下将网站部署到生产中。

调试模式的主要功能之一是显示详细的错误页面。如果你的应用程序在 DEBUG 为 True 时引发了异常，Django 会显示一个详细的回溯，包括很多关于你的环境的元数据，比如所有当前定义的 Django 配置（来自 settings.py）。

作为一项安全措施，Django将不包含可能是敏感的配置，如 SECRET_KEY。具体来说，它将排除任何名称中包含以下内容的配置。

'API'
'KEY'
'PASS'
'SECRET'
'SIGNATURE'
'TOKEN'

请注意，这些是部分匹配。'PASS' 也将与 PASSWORD 匹配，正如 'TOKEN' 也将与 TOKENIZED 匹配，以此类推。

不过，请注意，你的调试输出中总会有一些部分是不适合公开的。文件路径、配置选项等都会给攻击者提供关于你的服务器的额外信息。

同样重要的是，当 DEBUG 开启时，Django 会记住它执行的每个 SQL 查询。这在调试时很有用，但在生产服务器上会迅速消耗内存。

最后，如果 DEBUG 为 False，还需要正确设置 ALLOWED_HOSTS 配置。否则，所有的请求都会以 “Bad Request (400) ” 返回。

备注

默认的 settings.py 文件由 django-admin startproject 创建，为了方便，设置 DEBUG = True。

`DEBUG_PROPAGATE_EXCEPTIONS`

默认：False

如果设置为 True，则跳过 Django 对视图函数的异常处理（handler500，或者如果 DEBUG 为 True 则使用调试视图），以及对 500 响应的日志记录（django.request），异常会向上传播。

这对于一些测试配置是有用的。除非你想让你的 web 服务器（而不是 Django）生成“内部服务器错误”的响应，否则它不应该被用于实时站点。在这种情况下，确保你的服务器不会在响应中显示堆栈跟踪或其他敏感信息。

`DECIMAL_SEPARATOR`

默认： '.' （点）

格式化小数时使用的默认小数分隔符。

请注意，如果 USE_L10N 设置为 True，那么将采用本地决定的格式，具有更高的优先权。

另见 NUMBER_GROUPING、THOUSAND_SEPARATOR 和 USE_THOUSAND_SEPARATOR。

`DEFAULT_AUTO_FIELD`

默认： 'django.db.models.AutoField'

默认的主键字段类型，用于没有带有 primary_key=True 字段的模型。

迁移自动创建的中间表

当为多对多关系创建新的自动创建的中间表时，将尊重 DEFAULT_AUTO_FIELD 的值。

不幸的是，现有的自动创建的中间表的主键目前不能被迁移框架所更新。

这意味着，如果你切换了 DEFAULT_AUTO_FIELD 的值，然后生成迁移，相关模型的主键将被更新，来自中间表的外键也将被更新，但是自动创建的中间表的主键将不会被迁移。

为了解决这个问题，你应该在你的迁移中添加一个 RunSQL 操作来执行所需的 ALTER TABLE 步骤。你可以通过 sqlmigrate、dbshell 或字段的 remote_field.through._meta.db_table 属性来检查现有的表名。

通过模型明确定义的，已经由迁移系统处理。

允许对现有的自动创建的中间表的主键进行自动迁移可能会在以后实现。

`DEFAULT_CHARSET`

默认： 'utf-8'

如果没有手动指定 MIME 类型，所有 HttpResponse 对象将使用默认字符集。在构建 Content-Type 头时使用。

`DEFAULT_EXCEPTION_REPORTER`

默认： 'django.views.debug.ExceptionReporter'

如果还没有为 HttpRequest 实例分配任何异常报告类，则使用默认的异常报告类。参见自定义错误报告。

`DEFAULT_EXCEPTION_REPORTER_FILTER`

默认： 'django.views.debug.SafeExceptionReporterFilter'

如果还没有为 HttpRequest 实例分配任何异常报告过滤类，则使用默认的异常报告过滤类。参见过滤错误报告。

`DEFAULT_FILE_STORAGE`

默认： 'django.core.files.storage.FileSystemStorage'

默认的文件存储类，用于任何与文件相关的操作，不指定特定的存储系统。参见管理文件。

4.2 版后已移除: 这个设置已被弃用。从 Django 4.2 开始，可以使用 default 键下的 STORAGES 设置来配置默认文件存储引擎。

`DEFAULT_FROM_EMAIL`

默认： 'webmaster@localhost'

默认电子邮件地址，用于网站管理员的各种自动通信。这不包括发送到 ADMINS 和 MANAGERS 的错误信息；关于这一点，请参见 SERVER_EMAIL。

`DEFAULT_INDEX_TABLESPACE`

默认： '' （空字符串）

如果后端支持的话，在没有指定索引的字段上使用的默认表空间（参见表空间（Tablespaces））。

`DEFAULT_TABLESPACE`

默认： '' （空字符串）

对于没有指定表空间的模型，如果后端支持，则使用默认表空间（参见表空间（Tablespaces））。

`DISALLOWED_USER_AGENTS`

默认： [] （空列表）

编译后的正则表达式对象列表，代表全系统范围内不允许访问任何页面的 User-Agent 字符串。用于机器人／爬虫。只有在安装了 CommonMiddleware 的情况下才会使用（参见中间件）。

`EMAIL_BACKEND`

默认： 'django.core.mail.backends.smtp.EmailBackend'

用于发送邮件的后端。关于可用的后端列表，请参见发送邮件。

`EMAIL_FILE_PATH`

默认：未定义

文件邮件后端用来存储输出文件的目录。

`EMAIL_HOST`

默认： 'localhost'

用于发送电子邮件的主机。

另见 EMAIL_PORT。

`EMAIL_HOST_PASSWORD`

默认： '' （空字符串）

在 EMAIL_HOST 中定义的 SMTP 服务器使用的密码。这个配置和 EMAIL_HOST_USER 中的密码一起使用。如果这两个配置中的任何一个为空，Django 就不会尝试验证。

另见 EMAIL_HOST_USER。

`EMAIL_HOST_USER`

默认： '' （空字符串）

`EMAIL_SSL_CERTFILE`

默认： None

如果 EMAIL_USE_SSL 或 EMAIL_USE_TLS 是 True，你可以选择指定一个 PEM 格式的证书链文件的路径，用于 SSL 连接。

`EMAIL_SSL_KEYFILE`

默认： None

如果 EMAIL_USE_SSL 或 EMAIL_USE_TLS 为 True，你可以选择性地指定用于 SSL 连接的 PEM 格式化私钥文件的路径。

请注意，设置 EMAIL_SSL_CERTFILE 和 EMAIL_SSL_KEYFILE 不会导致任何证书检查。它们被传递给底层的 SSL 连接。有关证书链文件和私钥文件的处理方式的详细信息，请参阅 Python 的 ssl.SSLContext.wrap_socket() 函数的文档。

`EMAIL_TIMEOUT`

默认： None

指定阻止连接尝试等操作的超时时间，以秒为单位。

`FILE_UPLOAD_HANDLERS`

默认：

[
    "django.core.files.uploadhandler.MemoryFileUploadHandler",
    "django.core.files.uploadhandler.TemporaryFileUploadHandler",
]

上传过程中使用的处理程序列表。改变这个配置可以完全自定义——甚至替换——Django 的上传过程。

详情参见管理文件。

`FILE_UPLOAD_MAX_MEMORY_SIZE`

默认： 2621440 （即 2.5 MB）。

上传的文件在被传送到文件系统之前的最大尺寸（以字节为单位）。详见管理文件。

另见 DATA_UPLOAD_MAX_MEMORY_SIZE。

`FILE_UPLOAD_DIRECTORY_PERMISSIONS`

默认： None

适用于上传文件过程中创建的目录的数字模式。

当使用 collectstatic 管理命令时，这个配置也决定了收集的静态目录的默认权限。覆盖它的细节请参见 collectstatic。

这个值反映了 FILE_UPLOAD_PERMISSIONS 配置的功能和注意事项。

`FILE_UPLOAD_PERMISSIONS`

默认： 0o644

设置新上传文件的数字模式（即 0o644）。关于这些模式的更多信息，请参见 os.chmod() 的文档。

如果 None，你会得到操作系统依赖的行为。在大多数平台上，临时文件的模式为 0o600，从内存中保存的文件将使用系统的标准 umask 保存。

出于安全考虑，这些权限不应用于存储在 FILE_UPLOAD_TEMP_DIR 中的临时文件。

当使用 collectstatic 管理命令时，这个配置也决定了收集的静态文件的默认权限。覆盖它的细节请参见 collectstatic。

警告

总是在模式前加上 **`0o` 。**

如果你不熟悉文件模式，请注意 0o 的前缀是非常重要的：它表示一个八进制数，这就是模式必须被指定的方式。如果你试图使用 644，你会得到完全错误的行为。

`FILE_UPLOAD_TEMP_DIR`

默认： None

上传文件时要临时存储数据的目录（一般是大于 FILE_UPLOAD_MAX_MEMORY_SIZE 的文件）。如果 None，Django 将使用操作系统的标准临时目录。例如，在 *nix 风格的操作系统上，会默认为 /tmp。

详情参见管理文件。

`FIRST_DAY_OF_WEEK`

默认： 0 （星期日）

代表一周第一天的数字。这在显示日历时特别有用。该值仅在不使用格式国际化时使用，或者当无法为当前语言环境找到格式时使用。

该值必须是 0 到 6 的整数，其中 0 代表周日，1 代表周一，以此类推。

`FIXTURE_DIRS`

默认： [] （空列表）

除了每个应用程序的 fixtures 目录之外，按照搜索顺序列出用于搜索 fixture 文件的目录列表。

请注意，这些路径应该使用 Unix 风格的斜线，即使在 Windows 上也是如此。

参见使用固定数据提供数据和辅助工具加载。

`FORCE_SCRIPT_NAME`

默认： None

如果不是 None，将作为任何 HTTP 请求中 SCRIPT_NAME 环境变量的值。这个设置可以用来覆盖服务器提供的 SCRIPT_NAME 的值，这个值可能是首选值的重写版本，也可能根本没有提供。它还被 django.setup() 用来在请求／响应周期之外设置 URL 解析器脚本前缀（例如在管理命令和独立脚本中），以便在 SCRIPT_NAME 不是 / 时生成正确的 URL。

`FORM_RENDERER`

默认： 'django.forms.renderers.DjangoTemplates'

用于渲染表单和表单小部件的类。它必须实现低级渲染 API。包括的表单渲染器有：

'django.forms.renderers.DjangoTemplates'
'django.forms.renderers.Jinja2'
'django.forms.renderers.TemplatesSetting'

`FORMAT_MODULE_PATH`

默认： None

一个 Python 包的完整 Python 路径，该 Python 包包含了项目 locale 的自定义格式定义。如果不是 None，Django 将检查当前 locale 目录下的 formats.py 文件，并将使用该文件中定义的格式。

例如，如果 FORMAT_MODULE_PATH 设置为 mysite.formats，并且当前语言是 en （英语），Django 会期望一个类似以下的目录结构：

mysite/
    formats/
        __init__.py
        en/
            __init__.py
            formats.py

你也可以将此设置为 Python 路径列表，例如：

FORMAT_MODULE_PATH = [
    "mysite.formats",
    "some_app.formats",
]

当 Django 搜索某个格式时，它将通过所有给定的 Python 路径，直到找到一个真正定义该格式的模块。这意味着在列表中较远处的包中定义的格式将优先于较远处的包中的格式。

可用格式：

DATE_FORMAT
DATE_INPUT_FORMATS
DATETIME_FORMAT
DATETIME_INPUT_FORMATS
DECIMAL_SEPARATOR
FIRST_DAY_OF_WEEK
MONTH_DAY_FORMAT
NUMBER_GROUPING
SHORT_DATE_FORMAT
SHORT_DATETIME_FORMAT
THOUSAND_SEPARATOR
TIME_FORMAT
TIME_INPUT_FORMATS
YEAR_MONTH_FORMAT

`IGNORABLE_404_URLS`

默认： [] （空列表）

编译的正则表达式对象列表，这些对象描述了在通过电子邮件报告 HTTP 404 错误时应该被忽略的 URL（参见如何管理错误报告）。正则表达式与 request 的完整路径（包括查询字符串，如果有的话）进行匹配。如果你的网站没有提供常用的请求文件，如 favicon.ico 或 robots.txt，请使用此选项。

只有当 BrokenLinkEmailsMiddleware 被启用时，才会使用这个功能（参见中间件）。

`INSTALLED_APPS`

默认： [] （空列表）

一个字符串的列表，表示在这个 Django 安装中所有被启用的应用程序。每一个字符串都应该是一个 Python 的点分隔路径。

应用程序配置类（首选），或
包含应用程序的包。

了解更多关于应用配置。

使用应用程序注册进行自省

你的代码不应该直接访问 INSTALLED_APPS。使用 django.apps.apps 代替。

在 INSTLED_APPS 中，应用程序名称和标签必须是唯一的。

应用程序名称 ——指向应用程序包的点分隔 Python 路径——必须是唯一的。没有办法将同一个应用程序包含两次，除非用另一个名字复制它的代码。

应用程序标签 ——默认情况下，名称的最后一部分也必须是唯一的。例如，你不能同时包含 django.contrib.auth 和 myproject.auth。但是，你可以用自定义配置重新标注一个应用程序，定义不同的 label。

无论 INSTALLED_APPS 引用的是应用程序配置类还是应用包，这些规则都适用。

当多个应用程序提供同一资源的不同版本（模板、静态文件、管理命令、翻译）时， INSTALLED_APPS 中排在第一位的应用程序具有优先权。

`INTERNAL_IPS`

默认： [] （空列表）

一个 IP 地址的列表，作为字符串，它：

允许 debug() 上下文处理器为模板上下文添加一些变量。
即使不以员工用户身份登录，也可以使用管理文档书签。
在 AdminEmailHandler 邮件中被标记为“internal”（与 “EXTERNAL”相对）。

`LANGUAGE_CODE`

默认： 'en-us'

代表本次安装的语言代码的字符串。这应该是标准的 language ID 格式。例如，美国英语是 "en-us"。也请参见语言标识符列表和国际化和本地化。

:setting:`USE_I18N’ 必须是激活状态，该配置才会有效果。

它有两个作用：

如果没有使用 locale 中间件，它决定向所有用户提供哪种翻译。
如果 locale 中间件是激活的，它提供了一个后备语言，以防用户的首选语言无法确定或网站不支持。当用户的首选语言不存在给定字词的翻译时，它也会提供后备翻译。

更多细节请参考 Django 如何发现语言偏好。

`LANGUAGE_COOKIE_AGE`

默认： None （浏览器关闭时失效）

语言 cookie 的寿命，以秒为单位

`LANGUAGE_COOKIE_DOMAIN`

默认： None

语言 cookie 使用的域。将其设置为一个字符串，如 "example.com" 用于跨域 cookie，或使用 None 用于标准域 cookie。

在生产型网站上更新此配置时要谨慎。如果你更新此配置，在以前使用标准域 cookie 的网站上启用跨域 cookie，则现有的具有旧域的用户 cookie 将不会被更新。这将导致网站用户无法切换语言，只要这些 cookie 持续存在。执行切换的唯一安全可靠的方案是永久更改语言 cookie 名称（通过 LANGUAGE_COOKIE_NAME 设置），并添加一个中间件，将旧 cookie 的值复制到新 cookie 中，然后删除旧 cookie。

`LANGUAGE_COOKIE_HTTPONLY`

默认：False

是否对语言 cookie 使用 HttpOnly 标志。如果设置为 True，客户端的 JavaScript 将无法访问语言 cookie。

关于 HttpOnly 的详细信息，请参见 SESSION_COOKIE_HTTPONLY。

`LANGUAGE_COOKIE_NAME`

默认： 'django_language'

用于语言 cookie 的 cookie 名称。这可以是任何你想要的（只要它与你的应用程序中的其他 cookie 名称不同）。参见国际化和本地化。

`LANGUAGE_COOKIE_PATH`

默认： '/'

语言 cookie 上设置的路径。这个路径应该与你的 Django 安装的 URL 路径相匹配，或者是该路径的父路径。

如果你有多个 Django 实例在同一个主机名下运行，这个功能很有用。他们可以使用不同的 cookie 路径，每个实例只能看到自己的语言 cookie。

在生产型网站上更新此配置时要谨慎。如果你更新此配置，使用比以前更深的路径，则现有的用户 cookie 的旧路径将不会被更新。这将导致网站用户无法切换语言，只要这些 cookie 持续存在。执行切换的唯一安全可靠的方案是永久更改语言 cookie 的名称（通过 LANGUAGE_COOKIE_NAME 配置），并添加一个中间件，将旧 cookie 的值复制到新的 cookie 中，然后删除这个 cookie。

`LANGUAGE_COOKIE_SAMESITE`

默认： None

语言 cookie 上 SameSite 标志的值。该标志可防止在跨站点请求中发送 cookie。

关于 SameSite 的详细信息，请参见 SESSION_COOKIE_SAMESITE。

`LANGUAGE_COOKIE_SECURE`

默认：False

是否对语言 cookie 使用安全 cookie。如果设置为 True，cookie 将被标记为“安全”，这意味着浏览器可以确保 cookie 只在 HTTPS 连接下发送。

`LANGUAGES`

默认值。所有可用语言的清单。这个列表在不断的增加，如果在这里加入一个副本，那么不可避免的会很快过时。你可以在 django/conf/global_settings.py 中查看当前的翻译语言列表。

该列表是一个由两个元组组成的列表，其格式为 (language code, language name) ——例如，('ja', 'Japanese')。这指定了哪些语言可以选择。见国际化和本地化。

一般来说，默认值就可以了。只有当你想将语言选择限制在 Django 提供的语言子集时，才需要设置此配置。

如果你定义了一个自定义的 LANGUAGES 配置，你可以使用 gettext_lazy() 函数将语言名称标记为翻译字符串。

以下是一个示例配置文件：

from django.utils.translation import gettext_lazy as _
LANGUAGES = [
    ("de", _("German")),
    ("en", _("English")),
]

`LANGUAGES_BIDI`

默认值。所有从右到左书写的语言代码的列表。你可以在 django/conf/global_settings.py 中查看这些语言的当前列表。

列表中包含语言代码，用于从右到左书写的语言。

一般来说，默认值就可以了。只有当你想将语言选择限制在 Django 提供的语言子集时，才设置这个配置。如果你定义了一个自定义的 LANGUAGES 配置，双向语言列表中可能会包含一些在特定网站上没有启用的语言代码。

`LOCALE_PATHS`

默认： [] （空列表）

Django 寻找翻译文件的目录列表。参见 Django 如何发现翻译。

举例：

LOCALE_PATHS = [
    "/home/www/project/common_files/locale",
    "/var/local/translations/locale",
]

Django 会在这些路径中寻找包含实际翻译文件的 <locale_code>/LC_MESSAGES 目录。

`LOGGING`

默认：日志配置字典。

一个包含配置信息的数据结构。当不为空时，这个数据结构的内容将作为参数传递给 LOGGING_CONFIG 中描述的配置方法。

其中，当 DEBUG 为 False 时，默认的日志配置会将 HTTP 500 服务器错误传递给电子邮件日志处理程序。也请参见日志模块的配置。

你可以通过查看 django/utils/log.py 中的默认日志配置。

`LOGGING_CONFIG`

默认： 'logging.config.dictConfig'

Django 项目中用于配置日志的可调用路径。默认指向 Python 的 dictConfig 配置方法的实例。

如果将 LOGGING_CONFIG 配置为 None，将跳过日志配置过程。

`MANAGERS`

默认： [] （空列表）

一个与 ADMINS 格式相同的列表，用于指定当 BrokenLinkEmailsMiddleware 被启用时，谁应该收到断链通知。

`MEDIA_ROOT`

默认： '' （空字符串）

保存用户上传的文件目录的绝对文件系统路径。

例如： "/var/www/example.com/media/"

另见 MEDIA_URL。

警告

MEDIA_ROOT 和 STATIC_ROOT 必须有不同的值。在引入 STATIC_ROOT 之前，通常依靠或回溯 MEDIA_ROOT 来提供静态文件；然而，由于这可能会产生严重的安全影响，因此有一个验证检查来防止这种情况。

`MEDIA_URL`

默认： '' （空字符串）

处理从 MEDIA_ROOT 提供的媒体的 URL，用于管理存储文件。如果设置为非空值，则必须以斜线结束。在开发和生产环境中，你都需要配置这些文件被服务。

如果你想在模板中使用 {{ MEDIA_URL }}，在 TEMPLATES 的 ''context_processors' 选项中添加 'django.template.context_processors.media'。

例如： "http://media.example.com/"

警告

如果接收不受信任的用户的上传会有安全隐患，请阅读用户上传内容获取详情.

警告

MEDIA_URL 和 STATIC_URL 必须有不同的值。更多细节请参见 MEDIA_ROOT。

备注

如果 MEDIA_URL 是一个相对路径，那么它将以服务器提供的 SCRIPT_NAME 的值为前缀（如果没有设置，则为 /）。这使得在子路径中服务 Django 应用时更容易，而无需额外增加配置。

`MIDDLEWARE`

默认： None

要使用的中间件列表。参见中间件。

`MIGRATION_MODULES`

默认： {} （空字典）

一个指定包的字典，在每个应用程序的基础上可以找到迁移模块。这个配置的默认值是一个空字典，但迁移模块的默认包名是 migrations。

举例：

{"blog": "blog.db_migrations"}

在这种情况下，与 blog 应用有关的迁移将包含在 blog.db_migrations 包中。

如果你提供了 app_label 参数， makemigrations 将自动创建包，如果它还不存在。

当你为一个应用程序提供 None 作为一个值时，Django 会将该应用程序视为一个没有迁移的应用程序，而不考虑是否存在 migrations 子模块。例如，在测试设置文件中，这可以用来在测试时跳过迁移（仍然会为应用程序的模型创建表）。要在测试期间禁止所有应用程序的迁移，你可以将 MIGRATE 设置为 False。如果在你的一般项目配置中使用了 MIGRATION_MODULES，如果你想为应用程序创建表，记得使用 migrate —run-syncdb 选项。

`MONTH_DAY_FORMAT`

默认： 'F j'

在 Django admin change-list 页面上的日期字段的默认格式——也可能被系统的其他部分使用——在只显示月份和日期的情况下。

例如，当 Django 管理员的变更列表页面被日期 drilldown 过滤时，给定的一天的标题会显示日期和月份。不同的地域有不同的格式。例如，美国英语会说“January 1”，而西班牙语可能会说“1 Enero”。

请注意，如果 USE_L10N 设置为 True，则相应的本地决定的格式具有更高的优先权，并将被应用。

查看允许的日期格式字符串。另见 DATE_FORMAT、DATETIME_FORMAT、TIME_FORMAT 和 YEAR_MONTH_FORMAT。

`NUMBER_GROUPING`

默认： 0

一个数字的整数部分的数字组合在一起的数量。

常见的用途是显示千位数的分隔符。如果该设置为 0，则不会对该数字进行分组。如果这个设置大于 0，那么 THOUSAND_SEPARATOR 将被用作这些组之间的分隔符。

有些地方使用非统一的数字分组，例如 en_IN 中的 10,00,00,000。对于这种情况，你可以提供一个序列，其中包含要应用的数字组大小。第一个数字定义小数定界符之前的组的大小，后面的每个数字定义前面组的大小。如果序列以 -1 结束，则不会再进行分组。如果序列以 0 结束，则在剩余的数字中使用最后一组的大小。

en_IN 的元组示例：

NUMBER_GROUPING = (3, 2, 0)

请注意，如果 USE_L10N 设置为 True，那么将采用本地决定的格式，具有更高的优先权。

另见 DECIMAL_SEPARATOR、THOUSAND_SEPARATOR 和 USE_THOUSAND_SEPARATOR。

`PREPEND_WWW`

默认：False

是否给没有“www.”子域的 URL 加前缀。只有在安装了 CommonMiddleware 的情况下才会使用（参见中间件）。也请参见 APPEND_SLASH。

`ROOT_URLCONF`

默认：未定义

一个字符串，代表你的根 URLconf 的完整 Python 导入路径，例如 "mydjangoapps.urls"。可以通过在传入的 HttpRequest 对象上设置属性 urlconf 来覆盖每个请求。详情请参见 Django 如何处理一个请求。

`SECRET_KEY`

默认： '' （空字符串）

一个特定 Django 安装的密钥。用于提供加密签名，并且应该设置为一个唯一的、不可预测的值。

django-admin startproject 自动为每个新项目添加一个随机生成的 SECRET_KEY。

键的使用不应该假设是文本或字节。每次使用都应该通过 force_str() 或 force_bytes() 将其转换为所需类型。

如果 SECRET_KEY 没有设置，Django 将拒绝启动。

警告

将此值保密。

在已知的 SECRET_KEY 的情况下运行 Django，会破坏 Django 的许多安全保护措施，并可能导致权限升级和远程代码执行漏洞。

密钥用于：

所有会话如果你使用的是 django.contrib.session.backends.cache 以外的任何其他会话后端，或者使用的是默认的 get_session_auth_hash()。
所有消息，如果你使用了 CookieStorage 或 FallbackStorage。
所有 PasswordResetView 密钥。
加密签名的任何使用，除非提供不同的密钥。

当一个密钥不再设置为 SECRET_KEY 或包含在 SECRET_KEY_FALLBACKS 中时，上述所有内容都将无效。在旋转密钥时，你应该将旧密钥临时移动到 SECRET_KEY_FALLBACKS。密钥旋转不会影响用户的密码，密钥旋转不会影响用户的密码。

备注

默认的 settings.py 文件由 django-admin startproject 创建，为方便起见，创建了一个唯一的 SECRET_KEY。

`SECRET_KEY_FALLBACKS`

New in Django 4.1.

默认： []

一个特定 Django 安装的回退密钥列表。这些密钥用于允许旋转 SECRET_KEY。

为了旋转你的密钥，设置一个新的 SECRET_KEY 并将之前的值移动到 SECRET_KEY_FALLBACKS 的开头。然后在准备过期使用它们的会话、密码重置令牌等时，从 SECRET_KEY_FALLBACKS 的末尾删除旧值。

备注

签名操作计算成本较高。在 SECRET_KEY_FALLBACKS 中有多个旧密钥值会为所有与之前的密钥不匹配的检查增加额外的开销。

因此，在适当的时期后，应删除回退值，以允许密钥旋转。

密钥值的用途不应假定它们是文本或字节。每次使用应通过 force_str() 或 force_bytes() 进行转换为所需的类型。

`SECURE_CONTENT_TYPE_NOSNIFF`

默认： True

如果 True，则 SecurityMiddleware 会在所有响应中设置 X-Content-Type-Options: nosniff 头。

`SECURE_CROSS_ORIGIN_OPENER_POLICY`

默认： 'same-origin'

除非设置为 None，否则 SecurityMiddleware 会在所有没有此头的响应上设置跨域开启策略头部为提供的值。

`SECURE_HSTS_INCLUDE_SUBDOMAINS`

默认：False

如果 True，则 SecurityMiddleware 在 HTTP 严格传输安全头中添加 includeSubDomains 指令。除非 SECURE_HSTS_SECONDS 被设置为非零值，否则它没有任何效果。

警告

如果设置不正确，可能会不可逆地（对于 SECURE_HSTS_SECONDS 的值）破坏你的网站。请先阅读 HTTP 严格传输安全文档。

`SECURE_HSTS_PRELOAD`

默认：False

如果 True，则 SecurityMiddleware 在 HTTP 严格传输安全头中添加 preload 指令。除非 SECURE_HSTS_SECONDS 设置为非零值，否则没有效果。

`SECURE_HSTS_SECONDS`

默认： 0

如果设置为非零的整数值，则 SecurityMiddleware 会对所有尚未设置 HTTP 严格传输安全头的响应进行设置。

警告

不正确的设置可能会不可逆地（在一段时间内）破坏你的网站。请先阅读 HTTP 严格传输安全文档。

`SECURE_PROXY_SSL_HEADER`

默认： None

一个表示 HTTP 头部/值组合的元组，表示请求是安全的。这控制了请求对象的 is_secure() 方法的行为。

默认情况下，is_secure() 通过确认请求的 URL 使用 https:// 来判断请求是否安全。这个方法对 Django 的 CSRF 保护很重要，你自己的代码或第三方应用可能会用到它。

如果你的 Django 应用是在代理服务器后面，那么无论原始请求是否使用 HTTPS，代理服务器都可能会“吞噬”。如果代理和 Django 之间有一个非 HTTPS 的连接，那么 is_secure() 总是返回 False ——即使是终端用户通过 HTTPS 发出的请求。相反，如果代理和 Django 之间有 HTTPS 连接，那么 is_secure() 将总是返回 True ——即使是对最终用户通过 HTTPS 发出的请求。

在这种情况下，配置你的代理服务器，设置一个自定义的 HTTP 头，告诉 Django 这个请求是否是通过 HTTPS 进来的，并设置 SECURE_PROXY_SSL_HEADER，这样 Django 就知道要找什么头了。

设置一个包含两个元素的元组——要查找的头的名称和所需的值。例如：

SECURE_PROXY_SSL_HEADER = ("HTTP_X_FORWARDED_PROTO", "https")

这告诉 Django 信任来自代理的 X-Forwarded-Proto 头部，并且在以下情况下请求是安全的（即，它最初通过 HTTPS 进入）：

头部值为 'https'，或者
在协议的逗号分隔列表中，其初始、最左边的值为 'https' （例如，'https,http,http'）。

Changed in Django 4.1:

已添加对头部值中逗号分隔的协议列表的支持。

如果你控制了你的代理或者有其他的保证，你应该只设置这个配置，它可以适当地设置／剥离这个头。

需要注意的是，头的格式需要和 request.META 使用的格式一样——全大写，并且可能以 HTTP_ 开头。（记住，Django 会在 x-header 名称的开头自动加上 'HTTP_'，然后才会在 request.META 中使用。）

警告

修改此设置可能会危及你网站的安全。在更改之前，请确保你完全了解你的配置。

在设置之前，请确保以下所有内容为真（假设上面例子中的数值）。

你的 Django 应用在代理服务器后面。
你的代理会从所有传入的请求中剥离 X-Forwarded-Proto 头部，即使它包含逗号分隔的协议列表。换句话说，如果最终用户在他们的请求中包含该头部，代理会将其丢弃。
你的代理设置了 X-Forwarded-Proto 头，并将其发送给 Django，但只针对最初通过 HTTPS 进来的请求。

如果其中任何一个不是真的，你应该将这个配置设置为 None，并找到另一种确定 HTTPS 的方法，也许是通过自定义中间件。

`SECURE_REDIRECT_EXEMPT`

默认： [] （空列表）

如果一个 URL 路径与这个列表中的正则表达式相匹配，那么请求将不会被重定向到 HTTPS。SecurityMiddleware 会从 URL 路径中去掉前导斜杠，所以模式不应该包含它们，例如 SECURE_REDIRECT_EXEMPT = [r'^no-ssl/$', ...]。如果 SECURE_SSL_REDIRECT 是 False，这个配置就没有效果。

`SECURE_REFERRER_POLICY`

默认： 'same-origin'

如果设置了 SecurityMiddleware，则会在所有响应中设置 :ref:`referrer-policy`头，如果还没有该头，则将其设置为提供的值。

`SECURE_SSL_HOST`

默认： None

如果是一个字符串（如 secure.example.com），所有 SSL 重定向都将指向这个主机，而不是最初请求的主机（如 www.example.com）。如果 SECURE_SSL_REDIRECT 为 False，则该配置没有效果。

`SECURE_SSL_REDIRECT`

默认：False

如果 True，则 SecurityMiddleware 重定向所有非 HTTPS 的请求都会转为 HTTPS（除了那些匹配 SECURE_REDIRECT_EXEMPT 中所列正则表达式的 URL）。

备注

如果将此设置为 True 会导致无限重定向，这可能意味着你的网站是在代理服务器后面运行的，并且无法判断哪些请求是安全的，哪些不是。你的代理服务器可能会设置一个头来指示安全请求；你可以通过找出该头并相应地配置 SECURE_PROXY_SSL_HEADER 设置来纠正这个问题。

`SERIALIZATION_MODULES`

默认：未定义

一个包含序列化器定义（以字符串形式提供）的模块字典，以该序列化类型的字符串标识符为键。例如，要定义一个 YAML 序列化器，使用：

SERIALIZATION_MODULES = {"yaml": "path.to.yaml_serializer"}

`SERVER_EMAIL`

默认： 'root@localhost'

错误信息来自的电子邮件地址，例如发送到 ADMINS 和 MANAGERS 的邮件。

为什么我的邮件从不同的地址发送？

这个地址只用于错误信息。它不是用 send_mail() 发送普通邮件的地址；关于这个地址，请看 DEFAULT_FROM_EMAIL。

`SHORT_DATE_FORMAT`

默认：'m/d/Y' （例如 12/31/2003）

可用于在模板上显示日期字段的可用格式。请注意，如果 USE_L10N 被设置为 True，那么相应的本地决定的格式具有更高的优先权，并将被应用。参见允许的日期格式字符串。

另见 DATE_FORMAT 和 SHORT_DATETIME_FORMAT。

`SHORT_DATETIME_FORMAT`

默认： 'm/d/Y P' （例如 12/31/2003 4 p.m.）

可用于在模板上显示日期时间字段的可用格式。请注意，如果 USE_L10N 被设置为 True，那么相应的本地决定的格式具有更高的优先级，并将被应用。参见允许的日期格式字符串。

另见 DATE_FORMAT 和 SHORT_DATE_FORMAT。

`SIGNING_BACKEND`

默认： 'django.core.signing.TimestampSigner'

用于签署 cookie 和其他数据的后端。

另见加密签名文档。

`SILENCED_SYSTEM_CHECKS`

默认： [] （空列表）

你希望永久获取和忽略的系统检查框架生成的消息标识符列表（即 ["models.W001"]）。静默检查不会被输出到控制台。

另见系统检查框架文档。

`STORAGES`

New in Django 4.2.

默认：

{
    "default": {
        "BACKEND": "django.core.files.storage.FileSystemStorage",
    },
    "staticfiles": {
        "BACKEND": "django.contrib.staticfiles.storage.StaticFilesStorage",
    },
}

一个包含所有用于 Django 的存储设置的字典。它是一个嵌套字典，其内容将存储别名映射到包含单个存储选项的字典。

存储可以有您选择的任何别名。但是，有两个别名具有特殊意义：

default 用于管理文件。 'django.core.files.storage.FileSystemStorage' 是默认的存储引擎。
staticfiles 用于管理静态文件。 'django.contrib.staticfiles.storage.StaticFilesStorage' 是默认的存储引擎。

以下是定义名为 example 的自定义文件存储的示例 settings.py 片段：

STORAGES = {
    # ...
    "example": {
        "BACKEND": "django.core.files.storage.FileSystemStorage",
        "OPTIONS": {
            "location": "/example",
            "base_url": "/example/",
        },
    },
}

OPTIONS 在初始化时以 **kwargs 形式传递给 BACKEND。

可以从 django.core.files.storage.storages 获取存储后端的可用实例。使用与 STORAGES 中定义的后端相对应的键。

我的值与默认值合并吗？

定义此设置会覆盖默认值，而不会与默认值合并。

`TEMPLATES`

默认： [] （空列表）

一个包含所有 Django 模板引擎的配置的列表。列表中的每一项都是一个字典，包含了各个引擎的选项。

下面是一个配置，告诉 Django 模板引擎从每个安装好的应用程序中的 templates 子目录中加载模板：

TEMPLATES = [
    {
        "BACKEND": "django.template.backends.django.DjangoTemplates",
        "APP_DIRS": True,
    },
]

以下选项适用于所有后端。

`BACKEND`

默认：未定义

要使用的模板后端。内置的模板后端有：

'django.template.backends.django.DjangoTemplates'
'django.template.backends.jinja2.Jinja2'

你可以通过将 BACKEND 设置为一个完全限定的路径（例如 'mypackage.whatever.Backend'）来使用一个不在 Django 中的模板后端。

`NAME`

默认：见下方

这个特定模板引擎的别称。它是一个标识符，允许选择一个引擎进行渲染。所有配置的模板引擎的别名必须是唯一的。

它默认为定义引擎类的模块名称，即 BACKEND 的下一个到最后一个，如果没有提供的话。例如，如果后端是 'mypackage.whatever.Backend'，那么它的默认名称是 'whatever'。

`DIRS`

默认： [] （空列表）

按照搜索顺序，引擎应该查找模板源文件的目录。

`APP_DIRS`

默认：False

引擎是否应该在已安装的应用程序中查找模板源文件。

备注

默认的 settings.py 文件由 django-admin startproject 创建，设置 'APP_DIRS': True。

`OPTIONS`

默认值： {} （空字典）

要传递给模板后台的额外参数。根据模板后端的不同，可用的参数也不同。参见 DjangoTemplates 和 Jinja2 了解内置后端的选项。

`TEST_RUNNER`

默认： 'django.test.runner.DiscoverRunner'

用于启动测试套件的类的名称。参见使用不同的测试框架。

`TEST_NON_SERIALIZED_APPS`

默认： [] （空列表）

为了在 TransactionTestCase 和没有事务的数据库后端测试之间恢复数据库状态，Django 在启动测试运行时，会序列化所有应用的内容，这样就可以在运行需要的测试之前，从该副本重新加载。

这将减慢测试运行器的启动时间；如果你有一些应用程序不需要这个功能，你可以在这里添加它们的全名（例如 'django.contrib.contenttypes'），将它们从这个序列化过程中排除。

`THOUSAND_SEPARATOR`

默认： ',' （英文逗号）

格式化数字时使用的默认千位分隔符。只有当 USE_THOUSAND_SEPARATOR 为 True 和 NUMBER_GROUPING 大于 0 时，才使用此配置。

请注意，如果 USE_L10N 设置为 True，那么将采用本地决定的格式，具有更高的优先权。

另见 NUMBER_GROUPING、DECIMAL_SEPARATOR 和 USE_THOUSAND_SEPARATOR。

`TIME_FORMAT`

默认： 'P' （例如 4 p.m.）

在系统的任何部分显示时间字段时使用的默认格式。请注意，如果 USE_L10N 被设置为 True，那么本地决定的格式具有更高的优先权，并将被应用。参见允许的日期格式字符串。

另见 DATE_FORMAT 和 DATETIME_FORMAT。

`TIME_INPUT_FORMATS`

默认：

[
    "%H:%M:%S",  # '14:30:59'
    "%H:%M:%S.%f",  # '14:30:59.000200'
    "%H:%M",  # '14:30'
]

在时间字段上输入数据时可接受的格式列表。格式将按顺序被尝试，使用第一个有效的格式。注意这些格式字符串使用 Python 的 datetime 模块语法，而不是来自 date 模板过滤器的格式字符串。

当 USE_L10N 为 True 时，将采用本地规定的格式，具有更高的优先权。

另见 DATE_INPUT_FORMATS 和 DATETIME_INPUT_FORMATS。

`TIME_ZONE`

默认： 'America/Chicago'

表示本次安装的时区的字符串。参见时区列表。

备注

自从 Django 首次发布时， TIME_ZONE 设置为 'America/Chicago'，为了向后兼容，全局配置（如果你的项目 settings.py 中没有定义任何内容，则使用全局配置）仍为 'America/Chicago'。新项目模板默认为 'UTC'。

注意，这不一定是服务器的时区。例如，一个服务器可能服务于多个 Django 网站，每个网站都有单独的时区配置。

当 USE_TZ 为 False 时，这是 Django 存储所有日期时间的时区。当 USE_TZ 为 True 时，这是 Django 在模板中显示日期时间和解释表单中输入的日期时间的默认时区。

在 Unix 环境下（实现了 time.tzset()），Django 将 os.environ['TZ'] 变量设置为你在 TIME_ZONE 配置中指定的时区。这样，你所有的视图和模型都会自动在这个时区运行。但是，如果你使用的是手动设置配置中描述的手动配置选项，Django 就不会设置 TZ 环境变量。如果 Django 没有设置 TZ 环境变量，那么就需要你确保你的进程运行在正确的环境中。

备注

Django 无法在 Windows 环境下可靠地使用交替时区。如果你在 Windows 上运行 Django， TIME_ZONE 必须设置为与系统时区匹配。

`USE_DEPRECATED_PYTZ`

默认：False

一个布尔值，指定是否使用 pytz 作为默认的时区实现，而不是 zoneinfo。

4.0 版后已移除: 这个过渡性的设置已被弃用。在 Django 5.0 中将移除对使用 pytz 的支持。

`USE_I18N`

默认： True

一个布尔值，用于指定是否应该启用 Django 的翻译系统。这提供了一个关闭翻译系统的方法，以保证性能。如果设置为 False，Django 会进行一些优化，以避免加载翻译机制。

另见 LANGUAGE_CODE'、 :setting:`USE_L10N 和 :setting:`USE_TZ’。

备注

默认的 settings.py 文件由 django-admin startproject 创建，包括方便起见 USE_I18N = True。

`USE_L10N`

默认： True

一个布尔值，用于指定是否默认启用数据的本地化格式。如果设置为 True，例如，Django 将使用当前语言的格式来显示数字和日期。

另见 LANGUAGE_CODE、USE_I18N 和 USE_TZ。

4.0 版后已移除: 这个设置已被弃用。从 Django 5.0 开始，数据的本地化格式化将始终启用。例如，Django 将使用当前区域设置的格式显示数字和日期。

`USE_THOUSAND_SEPARATOR`

默认：False

一个布尔值，指定是否使用千位分隔符显示数字。当设置为 True 并且 USE_L10N 也为 True 时，Django 将使用 NUMBER_GROUPING 和 THOUSAND_SEPARATOR 设置格式化数字。后两个设置也可以由区域设置规定，以区域设置为优先。

另见 DECIMAL_SEPARATOR、NUMBER_GROUPING 和 THOUSAND_SEPARATOR。

`USE_TZ`

默认：False

备注

在 Django 5.0 中，默认值将从``False`` 更改为``True``。

一个布尔值，用于指定 Django 是否默认使用时区感知。如果设置为 True，Django 将在内部使用时区感知的日期。

当 USE_TZ 为 False 时，Django 将使用本地时间的本地日期，除非在解析 ISO 8601 格式的字符串时，如果存在时区信息，则会一直保留。

另见 TIME_ZONE、USE_I18N 和 USE_L10N。

备注

默认的 settings.py 文件由 django-admin startproject 创建，包括方便起见 USE_TZ = True。

`USE_X_FORWARDED_HOST`

默认：False

一个布尔值，用于指定是否使用 X-Forwarded-Host 头，而不是 Host 头。只有在使用设置该头的代理时才应启用。

此设置优先于 USE_X_FORWARDED_PORT。根据 RFC 7239#section-5.3，X-Forwarded-Host 头可以包括端口号，在这种情况下，你不应该使用 USE_X_FORWARDED_PORT。

`USE_X_FORWARDED_PORT`

默认：False

一个布尔值，用于指定是否使用 X-Forwarded-Port 头，而不是 SERVER_PORT``META 变量。只有在使用设置该头的代理时，才应启用。

USE_X_FORWARDED_HOST 优先于此配置。

`WSGI_APPLICATION`

默认： None

Django 内置服务器（如 runserver）将使用的 WSGI 应用对象的完整 Python 路径。django-admin startproject 管理命令将创建一个标准的 wsgi.py 文件，其中有一个 application 可调用，并将此配置指向该 application。

如果没有设置，将使用 django.core.wsgi.get_wsgi_application() 的返回值。在这种情况下， runserver 的行为将与之前的 Django 版本相同。

`YEAR_MONTH_FORMAT`

默认： 'F Y'

在 Django admin change-list 页面中，当只显示年和月的时候，默认的日期字段的格式也可能被系统的其他部分使用。

例如，当 Django 管理员的变更列表页面被日期 drilldown 过滤时，给定月份的头显示月份和年份。不同的地域有不同的格式。例如，美国英语会说“January 2006”，而另一个地方语言可能会说 “2006/January”。

请注意，如果 USE_L10N 设置为 True，则相应的本地决定的格式具有更高的优先权，并将被应用。

查看允许的日期格式字符串。另见 DATE_FORMAT、DATETIME_FORMAT、TIME_FORMAT 和 MONTH_DAY_FORMAT。

`X_FRAME_OPTIONS`

默认： 'DENY'

XFrameOptionsMiddleware 使用的 X- Frame-Options 头的默认值。参见点击劫持保护文档。

认证

django.contrib.auth 的配置。

`AUTHENTICATION_BACKENDS`

默认： ['django.contrib.auth.backends.ModelBackend']

当试图认证用户时，要使用的认证后端类（字符串）列表。详情请参见认证后端文档。

`AUTH_USER_MODEL`

默认： 'auth.User'

用来表示用户的模型。见替换一个自定义的 User 模型。。

警告

在项目的生命周期内（即一旦你制作并迁移了依赖它的模型），你无法不费吹灰之力地更改 AUTH_USER_MODEL 配置。它的目的是在项目开始时设置，并且它所引用的模型必须在它所在的应用程序的第一次迁移中可用。详见替换一个自定义的 User 模型。。

`LOGIN_REDIRECT_URL`

默认： '/accounts/profile/'

当 LoginView 没有得到 next GET 参数时，登录后请求被重定向的 URL 或命名 URL 模式。

`LOGIN_URL`

默认： '/accounts/login/'

当使用 login_required() 装饰器、LoginRequiredMixin 或 AccessMixin 时，重定向请求登录的 URL 或命名 URL 模式。

`LOGOUT_REDIRECT_URL`

默认： None

如果 LogoutView 没有 next_page 属性，则注销后重定向请求的 URL 或命名 URL 模式。

如果 None，将不执行重定向，并显示注销视图。

`PASSWORD_RESET_TIMEOUT`

默认： 259200 （3 天，以秒为单位）

密码重置链接的有效秒数。

由 PasswordResetConfirmView 使用。

备注

减少这个超时的值并不会对攻击者强行重置密码令牌的能力产生任何影响。令牌的设计是安全的，不需要任何超时。

这个超时时间的存在，是为了防止一些不太可能发生的攻击情况，比如有人访问可能包含旧的、未使用的密码重置令牌的电子邮件档案。

`PASSWORD_HASHERS`

查看 Django 如何存储密码。

默认：

[
    "django.contrib.auth.hashers.PBKDF2PasswordHasher",
    "django.contrib.auth.hashers.PBKDF2SHA1PasswordHasher",
    "django.contrib.auth.hashers.Argon2PasswordHasher",
    "django.contrib.auth.hashers.BCryptSHA256PasswordHasher",
    "django.contrib.auth.hashers.ScryptPasswordHasher",
]

`AUTH_PASSWORD_VALIDATORS`

默认： [] （空列表）

用于检查用户密码强度的验证器列表。更多细节请参见密码验证。默认情况下，不执行验证，所有密码都被接受。

消息

django.contrib.messages 的配置。

`MESSAGE_LEVEL`

默认： messages.INFO

设置消息框架将记录的最小消息级别。详见消息级别。

避免循环导入

如果你在配置文件中覆盖了 MESSAGE_LEVEL，并依赖任何内置的常量，你必须直接导入常量模块以避免循环导入的可能性，例如：

from django.contrib.messages import constants as message_constants
MESSAGE_LEVEL = message_constants.DEBUG

如果需要，可以直接根据上面常量表中的数值来指定常量的数值。

`MESSAGE_STORAGE`

默认： 'django.contrib.messages.storage.fallback.FallbackStorage'

控制 Django 存储消息数据的地方。有效值是：

'django.contrib.messages.storage.fallback.FallbackStorage'
'django.contrib.messages.storage.session.SessionStorage'
'django.contrib.messages.storage.cookie.CookieStorage'

详见消息储存后端。

使用 cookie 的后端—— CookieStorage 和 FallbackStorage ——在设置它们的 cookie 时，使用 SESSION_COOKIE_DOMAIN、SESSION_COOKIE_SECURE 和 SESSION_COOKIE_HTTPONLY 的值。

`MESSAGE_TAGS`

默认：

{
    messages.DEBUG: "debug",
    messages.INFO: "info",
    messages.SUCCESS: "success",
    messages.WARNING: "warning",
    messages.ERROR: "error",
}

这设置了消息级别到消息标签的映射，通常在 HTML 中以 CSS 类的形式呈现。如果你指定了一个值，它将扩展默认值。这意味着你只需要指定那些你需要覆盖的值。更多细节请参考上面的显示消息。

避免循环导入

如果你在配置文件中覆盖了 MESSAGE_TAGS，并依赖任何内置的常量，你必须直接导入 constants 模块，以避免循环导入的可能性，例如：

from django.contrib.messages import constants as message_constants
MESSAGE_TAGS = {message_constants.INFO: ""}

如果需要，可以直接根据上面常量表中的数值来指定常量的数值。

会话

django.contrib.sessions 的配置。

`SESSION_CACHE_ALIAS`

默认： 'default'

如果你使用的是基于缓存的会话存储，这将选择要使用的缓存。

`SESSION_COOKIE_AGE`

默认： 1209600 （2 周，以秒为单位）

会话 cookie 的寿命，以秒为单位。

`SESSION_COOKIE_DOMAIN`

默认： None

用于会话 cookie 的域。将其设置为一个字符串，如 "example.com"，用于跨域 cookie，或使用 None 用于标准域 cookie。

要使用带有 CSRF_USE_SESSIONS 的跨域 cookie，你必须包括一个前导点（例如 ".example.com"），以适应 CSRF 中间件的引用检查。

在生产型网站上更新此配置时要谨慎。如果你更新此配置，在以前使用标准域 cookie 的网站上启用跨域 cookie，现有用户 cookie 将被设置为旧域。这可能导致他们无法登录，只要这些 cookie 持续存在。

这个配置也会影响到 django.contrib.messages 所设置的 cookies。

`SESSION_COOKIE_HTTPONLY`

默认： True

是否对会话 cookie 使用 HttpOnly 标志。如果设置为 True，客户端的 JavaScript 将无法访问会话 cookie。

HttpOnly 是包含在 Set-Cookie HTTP 响应头中的一个标志。它是 RFC 6265#section-4.1.2.6 标准中 Cookie 的一部分，可以作为一种有用的方式来降低客户端脚本访问受保护 Cookie 数据的风险。

这使得攻击者将跨站脚本漏洞升级为完全劫持用户的会话变得不那么简单。关闭这个功能的理由不多。你的代码不应该从 JavaScript 中读取会话 cookies。

`SESSION_COOKIE_NAME`

默认： 'sessionid'

用于会话的 cookie 的名称。这可以是任何你想要的（只要它与你的应用程序中的其他 cookie 名称不同）。

`SESSION_COOKIE_PATH`

默认： '/'

会话 cookie 上设置的路径。这个路径应该与你的 Django 安装的 URL 路径相匹配，或者是该路径的父路径。

如果你有多个 Django 实例在同一个主机名下运行，这个功能很有用。他们可以使用不同的 cookie 路径，而且每个实例只能看到自己的会话 cookie。

`SESSION_COOKIE_SAMESITE`

默认： 'Lax'

会话 cookie 上的 SameSite 标志的值。这个标志可以防止 cookie 在跨站请求中被发送，从而防止 CSRF 攻击，使一些窃取会话 cookie 的方法变得不可能。

该配置的可能值为：

'Strict' ：防止浏览器在所有跨站点浏览的情况下向目标站点发送 cookie，即使在使用常规链接时也是如此。

例如，对于类似 GitHub 的网站来说，这意味着如果登录的用户通过企业论坛或电子邮件链接到 GitHub 的私人项目，GitHub 将不会收到会话 cookie，用户将无法访问该项目。然而，银行网站很可能不允许从外部网站链接任何交易页面，因此 'Strict' 标志将是合适的。
'Lax' （默认）：为希望在用户从外部链接到达后保持用户登录会话的网站提供安全和可用性之间的平衡。

在 GitHub 的场景下，当跟随外部网站的常规链接时，会话 cookie 将被允许，而在 CSRF 倾向的请求方法（例如 POST）中被阻止。
'None' （字符串）：会话 cookie 将随所有同站和跨站请求发送。
False ：停用该标志。

备注

现代浏览器为 SameSite 标志提供了一个更安全的默认策略，并将假定 Lax 为没有明确配置值的 cookies。

`SESSION_COOKIE_SECURE`

默认：False

是否对会话 cookie 使用安全 cookie。如果设置为 True，cookie 将被标记为“安全”，这意味着浏览器可以确保 cookie 只在 HTTPS 连接下发送。

关闭这个配置并不是一个好主意，因为攻击者可以用数据包嗅探器捕获一个未加密的会话 cookie，并使用 cookie 来劫持用户的会话

`SESSION_ENGINE`

默认： 'django.contrib.sessions.backends.db'

控制 Django 存储会话数据的地方。包括的引擎有：

'django.contrib.sessions.backends.db'
'django.contrib.sessions.backends.file'
'django.contrib.sessions.backends.cache'
'django.contrib.sessions.backends.cached_db'
'django.contrib.sessions.backends.signed_cookies'

详见配置会话引擎。

`SESSION_EXPIRE_AT_BROWSER_CLOSE`

默认：False

是否在用户关闭浏览器时结束会话。参见浏览器长度会话与持久会话。

`SESSION_FILE_PATH`

默认： None

如果你使用的是基于文件的会话存储，那么这个选项设置了 Django 存储会话数据的目录，当使用默认值（None）时，Django 将使用系统的标准临时目录。

`SESSION_SAVE_EVERY_REQUEST`

默认：False

是否在每次请求时保存会话数据。如果这个配置是 False （默认），那么会话数据只有在被修改时才会被保存，也就是说，如果它的任何字典值被分配或删除，那么会话数据就会被保存。即使这个配置是活动的，也不会创建空会话。

`SESSION_SERIALIZER`

默认： 'django.contrib.sessions.serializers.JSONSerializer'

用于序列化会话数据的序列化器类的完整导入路径。包括的序列化器是：

'django.contrib.sessions.serializers.JSONSerializer'

参见会话序列化。

站点

django.contrib.sites 的配置。

`SITE_ID`

默认：未定义

当前网站在 django_site 数据库表中的 ID，为整数。这样，应用数据就可以挂到特定的站点上，一个数据库可以管理多个站点的内容。

静态文件

django.contrib.staticfiles 的配置。

`STATIC_ROOT`

默认： None

collectstatic 将收集静态文件进行部署的目录的绝对路径。

例如： "/var/www/example.com/static/"

如果 staticfiles contrib 应用已启用（如在默认的项目模板中）， collectstatic 管理命令将收集静态文件到这个目录。更多使用方法请参见管理静态文件的操作指南。

警告

这应该是一个初始为空的目标目录，用于将你的静态文件从其永久位置收集到一个目录中，以方便部署；它不是永久存储静态文件的地方。你应该在那些会被静态文件的 finders 找到的目录中进行，默认情况下，这些目录是 'static/' 应用子目录和你在 STATICFILES_DIRS 中包含的任何目录。

`STATIC_URL`

默认： None

引用位于 STATIC_ROOT 中的静态文件时要使用的 URL。

例如： "/static/" 或 "http://static.example.com/"

如果不是 None，这将被用作资源定义（Media 类）和静态文件应用的基本路径。

如果设置为非空值，必须以斜线结束。

你可能需要在开发中服务这些文件，在生产中肯定需要这样做。

备注

如果 STATIC_URL 是一个相对路径，那么它将以服务器提供的 SCRIPT_NAME 的值为前缀（如果没有设置，则为 /）。这使得在子路径中服务 Django 应用时更容易，而无需在增加额外的配置。

`STATICFILES_DIRS`

默认： [] （空列表）

这个配置定义了静态文件应用在启用 FileSystemFinder 查找器时将穿越的额外位置，例如，如果你使用 collectstatic 或 findstatic 管理命令或使用静态文件服务视图。

这应该被设置为包含附加文件目录完整路径的字符串列表，例如：

STATICFILES_DIRS = [
    "/home/special.polls.com/polls/static",
    "/home/polls.com/polls/static",
    "/opt/webfiles/common",
]

请注意，这些路径应该使用 Unix 风格的斜线，即使在 Windows 上也是如此（例如 "C:/Users/user/mysite/extra_static_content"）。

前缀（可选）

如果你想用一个额外的命名空间来引用其中一个位置的文件，你可以 可选的 提供一个前缀作为 (prefix, path) 的元组，例如：

STATICFILES_DIRS = [
    # ...
    ("downloads", "/opt/webfiles/stats"),
]

例如，假设你已经将 STATIC_URL 设置为 'static/'，那么 collectstatic 管理命令将会在 STATIC_ROOT 的 'downloads' 子目录中收集 “stats” 文件。

这将允许你在你的模板中用 '/static/downloads/polls_20101022.tar.gz' 引用本地文件 '/opt/webfiles/stats/polls_20101022.tar.gz'，例如：

<a href="{% static 'downloads/polls_20101022.tar.gz' %}">

`STATICFILES_STORAGE`

默认： 'django.contrib.staticfiles.storage.StaticFilesStorage'

使用 collectstatic 管理命令收集静态文件时要使用的文件存储引擎。

在此设置中定义的存储后端的可用实例可以在 django.core.files.storage.storages 中的 staticfiles 键下找到。

例如，参见从云服务或 CDN 提供静态文件服务。

4.2 版后已移除: 这个设置已被弃用。从 Django 4.2 开始，静态文件存储引擎可以使用 staticfiles 键下的 STORAGES 设置进行配置。

`STATICFILES_FINDERS`

默认：

[
    "django.contrib.staticfiles.finders.FileSystemFinder",
    "django.contrib.staticfiles.finders.AppDirectoriesFinder",
]

知道如何找到不同位置的静态文件的查找器后端列表。

默认情况下，将查找存储在 STATICFILES_DIRS 配置中的文件（使用 django.contrib.staticfiles.finders.FileSystemFinder）和每个应用程序的 static 子目录中的文件（使用 django.contrib.staticfiles.finders.AppDirectoriesFinder）。如果存在多个同名文件，将使用第一个找到的文件。

默认情况下，一个查找器是禁用的：django.contrib.staticfiles.finders.DefaultStorageFinder。如果将其添加到 STATICFILES_FINDERS 设置中，它将在 STORAGES 设置中的 default 键定义的默认文件存储中查找静态文件。

备注

当使用 AppDirectoriesFinder 查找器时，通过将应用添加到你的网站的 INSTALLED_APPS 配置中，确保你的应用程序可以通过 staticfiles 找到。

静态文件查找器目前被认为是一个私有接口，因此这个接口是没有文档的。

核心配置专题索引