Getting Help

el
en
es
fr
id
it
ja
ko
pl
pt-br
语言： zh-hans

2.0
2.1
2.2
3.0
3.1
4.0
4.1
4.2
5.0
dev
文档版本： 3.2

配置¶

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

警告

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

核心配置 ¶

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

`ABSOLUTE_URL_OVERRIDES`¶

默认： {} （空字典）

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

ABSOLUTE_URL_OVERRIDES = {
    'blogs.weblog': 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 头部，你就绕过了这种安全保护机制。

Changed in Django 3.1:

如果 ALLOWED_HOSTS 为空且 DEBUG=True，则允许使用 localhost 的子域。

`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'

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

Changed in Django 3.2:

增加了 PyMemcacheCache 后端。

`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，缓存条目不会过期。

`VERSION`¶

默认： 1

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

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

`CACHE_MIDDLEWARE_ALIAS`¶

默认： 'default'

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

`CACHE_MIDDLEWARE_KEY_PREFIX`¶

默认： '' （空字符串）

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

参见 Django 缓存框架。

`CACHE_MIDDLEWARE_SECONDS`¶

默认： 600

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

参见 Django 缓存框架。

`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）的可信来源主机列表。对于 可靠 的不安全请求，Django 的 CSRF 保护要求该请求的 Referer 头必须与 Host 头中的来源匹配。例如，这可以防止来自 subdomain.example.com 的 POST 请求对 api.example.com 成功。如果你需要通过 HTTPS 的跨源不安全请求，继续这个例子，在这个列表中添加 "subdomain.example.com"`。该设置还支持子域，所以你可以添加 ".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 则是无限的持久连接。

`OPTIONS`¶

默认： {} （空字典）

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

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

`PASSWORD`¶

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

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

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`¶

New in Django 3.1.

默认： True

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

`MIRROR`¶

默认： None

在测试过程中，该数据库应该镜像的数据库的别名。

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

`NAME`¶

默认： None

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

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

查看测试数据库。

`SERIALIZE`¶

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

默认： '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 服务器通常不会进行深层的请求检查，所以不可能在这个层面进行类似的检查。

`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', '%m/%d/%Y', '%m/%d/%y', # '2006-10-25', '10/25/2006', '10/25/06'
    '%b %d %Y', '%b %d, %Y',            # 'Oct 25 2006', 'Oct 25, 2006'
    '%d %b %Y', '%d %b, %Y',            # '25 Oct 2006', '25 Oct, 2006'
    '%B %d %Y', '%B %d, %Y',            # 'October 25 2006', 'October 25, 2006'
    '%d %B %Y', '%d %B, %Y',            # '25 October 2006', '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。

Changed in Django 3.1:

在旧版本中，默认的是一个包含仅有日期的格式的列表。

`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）和 Django 对 500 响应的记录（django.request）将被跳过，异常向上传播。

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

`DECIMAL_SEPARATOR`¶

默认： '.' （点）

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

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

另见 NUMBER_GROUPING、THOUSAND_SEPARATOR 和 USE_THOUSAND_SEPARATOR。

`DEFAULT_AUTO_FIELD`¶

New in Django 3.2.

默认： '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`¶

New in Django 3.1.

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

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

`DEFAULT_EXCEPTION_REPORTER_FILTER`¶

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

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

`DEFAULT_FILE_STORAGE`¶

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

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

`DEFAULT_FROM_EMAIL`¶

默认： 'webmaster@localhost'

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

`DEFAULT_HASHING_ALGORITHM`¶

New in Django 3.1.

默认： 'sha256'

默认的散列算法，用于对 cookie、管理员站点中的密码重置令牌、用户会话以及 django.core.signing.Signer 和 django.core.signing.dumps() 创建的签名进行编码。算法必须是 'sha1' 或 'sha256'。详细使用方法请参见发行说明。

3.1 版后已移除: 这个过渡性设置已经被废弃。它和使用 SHA-1 散列算法的 tokens、cookie、session 和签名的支持将在 Django 4.0 中被移除。

`DEFAULT_INDEX_TABLESPACE`¶

默认： '' （空字符串）

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

`DEFAULT_TABLESPACE`¶

默认： '' （空字符串）

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

`DISALLOWED_USER_AGENTS`¶

默认： [] （空列表）

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

`EMAIL_BACKEND`¶

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

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

`EMAIL_FILE_PATH`¶

默认：未定义

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

Changed in Django 3.1:

已添加对 pathlib.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.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 目录外，按搜索顺序列出了搜索辅助工具文件的目录。

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

参见通过固定内容提供数据和辅助工具加载。

`FORCE_SCRIPT_NAME`¶

默认： None

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

`FORM_RENDERER`¶

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

The class that renders form widgets. It must implement the low-level render API. Included form renderers are:

`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 如何发现语言偏好。

`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 密钥。
加密签名的任何使用，除非提供不同的密钥。

如果你轮换密钥，以上都将失效。密钥不用于用户的密码，轮换秘钥不会影响用户的密码。

注解

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

`SECURE_BROWSER_XSS_FILTER`¶

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

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

SECURE_PROXY_SSL_HEADER = ('HTTP_X_FORWARDED_PROTO', 'https')

这告诉 Django 信任来自我们代理的 X-Forwarded-Proto 头，任何时候它的值是 'https'，那么就保证请求是安全的（即原来是通过 HTTPS 进来的）。

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

需要注意的是，头的格式需要和 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`头，如果还没有该头，则将其设置为提供的值。

Changed in Django 3.1:

在旧版本中，默认值为 None。

`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"]）。静默检查不会被输出到控制台。

另见系统检查框架文档。

`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_I18N`¶

默认： True

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

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

注解

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

`USE_L10N`¶

默认：False

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

另见 LANGUAGE_CODE、USE_I18N 和 USE_TZ。

注解

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

`USE_THOUSAND_SEPARATOR`¶

默认：False

一个布尔值，用于指定是否使用千位分隔符显示数字。当设置为 True 且 USE_L10N 也为 True 时，Django 将使用 NUMBER_GROUPING 和 THOUSAND_SEPARATOR 配置来格式化数字。这些配置也可能由 locale 决定，以 locale 为准。

另见 DECIMAL_SEPARATOR、NUMBER_GROUPING 和 THOUSAND_SEPARATOR。

`USE_TZ`¶

默认：False

一个布尔值，用于指定 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 模型。。

`LOGOUT_REDIRECT_URL`¶

默认： None

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

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

`PASSWORD_RESET_TIMEOUT`¶

New in Django 3.1.

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

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

由 PasswordResetConfirmView 使用。

注解

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

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

`PASSWORD_RESET_TIMEOUT_DAYS`¶

默认： 3

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

由 PasswordResetConfirmView 使用。

3.1 版后已移除: 这个配置已被废弃了。使用 PASSWORD_RESET_TIMEOUT 代替。

`PASSWORD_HASHERS`¶

查看 Django 如何存储密码。

默认：

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

`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_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)引擎。

`SESSION_EXPIRE_AT_BROWSER_CLOSE`¶

默认：False

是否在用户关闭浏览器时结束会话。参见 Browser-length 会话 vs 持久会话。

`SESSION_FILE_PATH`¶

默认： None

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

`SESSION_SAVE_EVERY_REQUEST`¶

默认：False

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

`SESSION_SERIALIZER`¶

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

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

'django.contrib.sessions.serializers.PickleSerializer'
'django.contrib.sessions.serializers.JSONSerializer'

参见会话序列化了解详情，包括当使用 PickleSerializer 时可能会出现远程代码执行的警告。

站点 ¶

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.contrib.staticfiles.storage.staticfiles_storage 中找到。

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

`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 配置中，它将在 DEFAULT_FILE_STORAGE 配置所定义的默认文件存储中查找静态文件。

注解

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

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

核心配置专题索引 ¶

文档

配置¶

核心配置¶

ABSOLUTE_URL_OVERRIDES¶

ADMINS¶

ALLOWED_HOSTS¶

APPEND_SLASH¶

CACHES¶

BACKEND¶

KEY_FUNCTION¶

KEY_PREFIX¶

LOCATION¶

OPTIONS¶

TIMEOUT¶

VERSION¶

CACHE_MIDDLEWARE_ALIAS¶

CACHE_MIDDLEWARE_KEY_PREFIX¶

CACHE_MIDDLEWARE_SECONDS¶

CSRF_COOKIE_AGE¶

CSRF_COOKIE_DOMAIN¶

CSRF_COOKIE_HTTPONLY¶

CSRF_COOKIE_NAME¶

CSRF_COOKIE_PATH¶

CSRF_COOKIE_SAMESITE¶

CSRF_COOKIE_SECURE¶

CSRF_USE_SESSIONS¶

CSRF_FAILURE_VIEW¶

CSRF_HEADER_NAME¶

CSRF_TRUSTED_ORIGINS¶

DATABASES¶

ATOMIC_REQUESTS¶

AUTOCOMMIT¶

ENGINE¶

HOST¶

NAME¶

CONN_MAX_AGE¶

OPTIONS¶

PASSWORD¶

PORT¶

TIME_ZONE¶

DISABLE_SERVER_SIDE_CURSORS¶

USER¶

TEST¶

CHARSET¶

COLLATION¶

DEPENDENCIES¶

MIGRATE¶

MIRROR¶

NAME¶

SERIALIZE¶

TEMPLATE¶

CREATE_DB¶

CREATE_USER¶

USER¶

PASSWORD¶

ORACLE_MANAGED_FILES¶

TBLSPACE¶

TBLSPACE_TMP¶

DATAFILE¶

DATAFILE_TMP¶

DATAFILE_MAXSIZE¶

DATAFILE_TMP_MAXSIZE¶

DATAFILE_SIZE¶

DATAFILE_TMP_SIZE¶

DATAFILE_EXTSIZE¶

DATAFILE_TMP_EXTSIZE¶

DATA_UPLOAD_MAX_MEMORY_SIZE¶

DATA_UPLOAD_MAX_NUMBER_FIELDS¶

DATABASE_ROUTERS¶

DATE_FORMAT¶

DATE_INPUT_FORMATS¶

DATETIME_FORMAT¶

DATETIME_INPUT_FORMATS¶

DEBUG¶

DEBUG_PROPAGATE_EXCEPTIONS¶

DECIMAL_SEPARATOR¶

DEFAULT_AUTO_FIELD¶

DEFAULT_CHARSET¶

DEFAULT_EXCEPTION_REPORTER¶

DEFAULT_EXCEPTION_REPORTER_FILTER¶

核心配置 ¶

`ABSOLUTE_URL_OVERRIDES`¶

`ADMINS`¶

`ALLOWED_HOSTS`¶

`APPEND_SLASH`¶

`CACHES`¶

`BACKEND`¶

`KEY_FUNCTION`¶

`KEY_PREFIX`¶

`LOCATION`¶

`OPTIONS`¶

`TIMEOUT`¶

`VERSION`¶

`CACHE_MIDDLEWARE_ALIAS`¶

`CACHE_MIDDLEWARE_KEY_PREFIX`¶

`CACHE_MIDDLEWARE_SECONDS`¶

`CSRF_COOKIE_AGE`¶

`CSRF_COOKIE_DOMAIN`¶

`CSRF_COOKIE_HTTPONLY`¶

`CSRF_COOKIE_NAME`¶

`CSRF_COOKIE_PATH`¶

`CSRF_COOKIE_SAMESITE`¶

`CSRF_COOKIE_SECURE`¶

`CSRF_USE_SESSIONS`¶

`CSRF_FAILURE_VIEW`¶

`CSRF_HEADER_NAME`¶

`CSRF_TRUSTED_ORIGINS`¶

`DATABASES`¶

`ATOMIC_REQUESTS`¶

`AUTOCOMMIT`¶

`ENGINE`¶

`HOST`¶

`NAME`¶

`CONN_MAX_AGE`¶

`OPTIONS`¶

`PASSWORD`¶

`PORT`¶

`TIME_ZONE`¶

`DISABLE_SERVER_SIDE_CURSORS`¶

`USER`¶

`TEST`¶

`CHARSET`¶

`COLLATION`¶

`DEPENDENCIES`¶

`MIGRATE`¶

`MIRROR`¶

`NAME`¶

`SERIALIZE`¶

`TEMPLATE`¶

`CREATE_DB`¶

`CREATE_USER`¶

`USER`¶

`PASSWORD`¶

`ORACLE_MANAGED_FILES`¶

`TBLSPACE`¶

`TBLSPACE_TMP`¶

`DATAFILE`¶

`DATAFILE_TMP`¶

`DATAFILE_MAXSIZE`¶

`DATAFILE_TMP_MAXSIZE`¶

`DATAFILE_SIZE`¶

`DATAFILE_TMP_SIZE`¶

`DATAFILE_EXTSIZE`¶

`DATAFILE_TMP_EXTSIZE`¶

`DATA_UPLOAD_MAX_MEMORY_SIZE`¶

`DATA_UPLOAD_MAX_NUMBER_FIELDS`¶

`DATABASE_ROUTERS`¶

`DATE_FORMAT`¶

`DATE_INPUT_FORMATS`¶

`DATETIME_FORMAT`¶

`DATETIME_INPUT_FORMATS`¶

`DEBUG`¶

`DEBUG_PROPAGATE_EXCEPTIONS`¶

`DECIMAL_SEPARATOR`¶

`DEFAULT_AUTO_FIELD`¶

`DEFAULT_CHARSET`¶

`DEFAULT_EXCEPTION_REPORTER`¶

`DEFAULT_EXCEPTION_REPORTER_FILTER`¶

`DEFAULT_FILE_STORAGE`¶

`DEFAULT_FROM_EMAIL`¶