设置 — Django 文档

来自菜鸟教程
Django/docs/3.0.x/ref/settings
跳转至:导航、​搜索

设置

警告

覆盖设置时要小心,尤其是当默认值是非空列表或字典时,例如 :setting:`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

默认值:[](空列表)

收到代码错误通知的所有人员的列表。 什么时候 :设置:`调试=假 `管理员电子邮件处理程序配置在 :设置:`日志` (默认完成),Django 会通过电子邮件向这些人发送请求/响应周期中引发的异常的详细信息。

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

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

ALLOWED_HOSTS

默认值:[](空列表)

表示此 Django 站点可以提供的主机/域名的字符串列表。 这是一种防止 HTTP 主机标头攻击 的安全措施,即使在许多看似安全的 Web 服务器配置下也是可能的。

此列表中的值可以是完全限定名称(例如 'www.example.com'),在这种情况下,它们将与请求的 Host 标头完全匹配(不区分大小写,不包括端口)。 以句点开头的值可以用作子域通配符:'.example.com' 将匹配 example.comwww.example.comexample.com 的任何其他子域。 '*' 的值将匹配任何内容; 在这种情况下,您有责任提供自己对 Host 标头的验证(可能在中间件中;如果是这样,则该中间件必须首先在 :setting:`MIDDLEWARE` 中列出)。

Django 还允许任何条目的 完全限定域名 (FQDN)。 某些浏览器在 Host 标头中包含一个尾随点,Django 在执行主机验证时将其去除。

如果 Host 标头(或 X-Forwarded-Host 如果 :setting:`USE_X_FORWARDED_HOST` 已启用)与此列表中的任何值不匹配,则 django.http。 HttpRequest.get_host() 方法将引发 SuspiciousOperation

:setting:`DEBUG`TrueALLOWED_HOSTS 为空时,根据 ['localhost', '127.0.0.1', '[::1]'] 验证主机。

ALLOWED_HOSTS 在运行测试 时也被检查

此验证仅适用于 get_host(); 如果您的代码直接从 request.META 访问 Host 标头,则您将绕过此安全保护。


APPEND_SLASH

默认值:True

当设置为 True 时,如果请求 URL 与 URLconf 中的任何模式都不匹配,并且它不以斜杠结尾,则 HTTP 重定向将发送到附加斜杠的同一 URL。 请注意,重定向可能会导致在 POST 请求中提交的任何数据丢失。

:setting:`APPEND_SLASH` 设置仅在安装了 CommonMiddleware 时使用(参见 Middleware)。 另见 :setting:`PREPEND_WWW`


CACHES

默认:

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

包含要与 Django 一起使用的所有缓存的设置的字典。 它是一个嵌套字典,其内容将缓存别名映射到包含单个缓存选项的字典。

:setting:`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.MemcachedCache'
  • 'django.core.cache.backends.memcached.PyLibMCCache'

您可以通过设置使用不随 Django 一起提供的缓存后端 :设置:`后端 ` 到缓存后端类的完全限定路径(即 mypackage.backends.whatever.WhateverCache)。


KEY_FUNCTION

包含函数(或任何可调用)的虚线路径的字符串,该字符串定义了如何将前缀、版本和键组合成最终缓存键。 默认实现等价于函数:

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

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

有关更多信息,请参阅 缓存文档


KEY_PREFIX

默认值:(空字符串)

将自动包含(默认为前置)到 Django 服务器使用的所有缓存键的字符串。

有关更多信息,请参阅 缓存文档


LOCATION

默认值:(空字符串)

要使用的缓存的位置。 这可能是文件系统缓存的目录、内存缓存服务器的主机和端口,或本地内存缓存的标识名称。 例如:

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.sessions

将 CSRF 令牌存储在 cookie(Django 的默认设置)中是安全的,但将其存储在会话中是其他 Web 框架中的常见做法,因此有时安全审计员会要求这样做。

由于 默认错误视图 需要 CSRF 令牌,因此 SessionMiddleware 必须出现在 :setting:`MIDDLEWARE` 中,然后出现在任何可能引发异常以触发错误的中间件之前如果您使用 CSRF_USE_SESSIONS,请查看(例如 PermissionDenied)。 请参阅 中间件订购


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)。 对于 secure 不安全请求,Django 的 CSRF 保护要求该请求具有 Referer 标头,该标头与 Host 标头中存在的原点匹配。 例如,这可以防止来自 subdomain.example.comPOST 请求成功针对 api.example.com。 如果您需要通过 HTTPS 的跨源不安全请求,继续示例,将 "subdomain.example.com" 添加到此列表。 该设置还支持子域,因此您可以添加 ".example.com",例如,允许从 example.com 的所有子域访问。


DATABASES

默认值:{}(空字典)

包含要与 Django 一起使用的所有数据库的设置的字典。 它是一个嵌套字典,其内容将数据库别名映射到包含单个数据库选项的字典。

:setting:`DATABASES`设置必须配置一个default数据库; 还可以指定任意数量的附加数据库。

最简单的设置文件适用于使用 SQLite 的单数据库设置。 这可以使用以下内容进行配置:

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

当连接到其他数据库后端时,例如 MariaDB、MySQL、Oracle 或 PostgreSQL,将需要额外的连接参数。 见 :设置:`引擎 ` 下面关于如何指定其他数据库类型的设置。 此示例适用于 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)。


HOST

默认值:(空字符串)

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

如果此值以正斜杠 ('/') 开头并且您使用的是 MySQL,则 MySQL 将通过 Unix 套接字连接到指定的套接字。 例如:

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

如果您正在使用 MySQL 并且此值 不以正斜杠 开头,则假定此值是主机。

如果您使用的是 PostgreSQL,默认情况下(空 :setting:`HOST`),到数据库的连接是通过 UNIX 域套接字(pg_hba.conf 中的“本地”行)完成的。 如果您的 UNIX 域套接字不在标准位置,请使用与 postgresql.conf 相同的 unix_socket_directory 值。 如果要通过 TCP 套接字连接,请将 :setting:`HOST` 设置为“localhost”或“127.0.0.1”(pg_hba.conf 中的“host”行)。 在 Windows 上,您应该始终定义 :setting:`HOST`,因为 UNIX 域套接字不可用。


NAME

默认值:(空字符串)

要使用的数据库的名称。 对于 SQLite,它是数据库文件的完整路径。 指定路径时,始终使用正斜杠,即使在 Windows 上(例如 C:/homes/user/mysite/sqlite3.db)。


CONN_MAX_AGE

默认值:0

数据库连接的生命周期,以秒为单位。 使用 0 在每个请求结束时关闭数据库连接 - Django 的历史行为 - 和 None 用于无限制的持久连接。


OPTIONS

默认值:{}(空字典)

连接到数据库时要使用的额外参数。 可用参数因数据库后端而异。

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


PASSWORD

默认值:(空字符串)

连接到数据库时使用的密码。 不与 SQLite 一起使用。


PORT

默认值:(空字符串)

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


TIME_ZONE

默认值:None

表示存储在此数据库中的日期时间的时区的字符串(假设它不支持时区)或 None:setting:`DATABASES` 设置的这个内部选项接受与一般 :setting:`TIME_ZONE` 设置相同的值。

这允许与以本地时间而不是 UTC 存储日期时间的第三方数据库进行交互。 为避免 DST 更改引起的问题,您不应为 Django 管理的数据库设置此选项。

:setting:`USE_TZ`True 并且数据库不支持时区(例如 SQLite、MySQL、Oracle),如果设置了此选项,Django 将根据本地时间读取和写入日期时间,如果未设置,则使用 UTC。

:setting:`USE_TZ`True 并且数据库支持时区(例如 PostgreSQL),设置这个选项是错误的。

:setting:`USE_TZ`False 时,设置该选项是错误的。


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 之外的所有数据库,它没有依赖关系。

数据库的创建顺序依赖项。 有关详细信息,请参阅有关 控制测试数据库的创建顺序 的文档。


MIRROR

默认值:None

此数据库在测试期间应镜像的数据库的别名。

此设置的存在允许测试多个数据库的主/副本(某些数据库称为主/从)配置。 有关详细信息,请参阅有关 测试主/副本配置 的文档。


NAME

默认值:None

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

如果 SQLite 数据库引擎使用默认值 (None),则测试将使用内存驻留数据库。 对于所有其他数据库引擎,测试数据库将使用名称 'test_' + DATABASE_NAME

参见测试数据库


SERIALIZE

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


TEMPLATE

这是特定于 PostgreSQL 的设置。

模板 的名称(例如 'template0') 从中创建测试数据库。


CREATE_DB

默认值:True

这是特定于 Oracle 的设置。

如果设置为 False,测试表空间不会在测试开始时自动创建或在测试结束时删除。


CREATE_USER

默认值:True

这是特定于 Oracle 的设置。

如果设置为False,测试用户不会在测试开始时自动创建并在测试结束时自动删除。


USER

默认值:None

这是特定于 Oracle 的设置。

连接到运行测试时将使用的 Oracle 数据库时使用的用户名。 如果未提供,Django 将使用 'test_' + USER


PASSWORD

默认值:None

这是特定于 Oracle 的设置。

连接到运行测试时将使用的 Oracle 数据库时使用的密码。 如果未提供,Django 将生成一个随机密码。


ORACLE_MANAGED_FILES

2.2 版中的新功能。


默认值:False

这是特定于 Oracle 的设置。

如果设置为 True,将使用 Oracle Managed Files (OMF) 表空间。 :setting:`DATAFILE`:setting:`DATAFILE_TMP` 将被忽略。


TBLSPACE

默认值:None

这是特定于 Oracle 的设置。

运行测试时将使用的表空间的名称。 如果未提供,Django 将使用 'test_' + USER


TBLSPACE_TMP

默认值:None

这是特定于 Oracle 的设置。

运行测试时将使用的临时表空间的名称。 如果未提供,Django 将使用 'test_' + USER + '_temp'


DATAFILE

默认值:None

这是特定于 Oracle 的设置。

用于 TBLSPACE 的数据文件的名称。 如果未提供,Django 将使用 TBLSPACE + '.dbf'


DATAFILE_TMP

默认值:None

这是特定于 Oracle 的设置。

用于 TBLSPACE_TMP 的数据文件的名称。 如果未提供,Django 将使用 TBLSPACE_TMP + '.dbf'


DATAFILE_MAXSIZE

默认值:'500M'

这是特定于 Oracle 的设置。

允许 DATAFILE 增长到的最大大小。


DATAFILE_TMP_MAXSIZE

默认值:'500M'

这是特定于 Oracle 的设置。

允许 DATAFILE_TMP 增长到的最大大小。


DATAFILE_SIZE

默认值:'50M'

这是特定于 Oracle 的设置。

DATAFILE 的初始大小。


DATAFILE_TMP_SIZE

默认值:'50M'

这是特定于 Oracle 的设置。

DATAFILE_TMP 的初始大小。


DATAFILE_EXTSIZE

默认值:'25M'

这是特定于 Oracle 的设置。

需要更多空间时扩展 DATAFILE 的量。


DATAFILE_TMP_EXTSIZE

默认值:'25M'

这是特定于 Oracle 的设置。

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


DATA_UPLOAD_MAX_MEMORY_SIZE

默认值:2621440(即 2.5 MB)。

请求正文在 SuspiciousOperation (RequestDataTooBig) 之前可能存在的最大字节大小。 该检查在访问 request.bodyrequest.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)

用于在系统的任何部分显示日期字段的默认格式。 请注意,如果 :setting:`USE_L10N` 设置为 True,则语言环境指定的格式具有更高的优先级并将被应用。 看 :tfilter:`允许的日期格式字符串 ` .

另见 :setting:`DATETIME_FORMAT`:setting:`TIME_FORMAT`:setting:`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 模块语法 ,而不是来自 :tfilter:`date` 模板过滤器的格式字符串。

:setting:`USE_L10N`True 时,语言环境指定的格式具有更高的优先级,将改为应用。

另见 :setting:`DATETIME_INPUT_FORMATS`:setting:`TIME_INPUT_FORMATS`


DATETIME_FORMAT

默认值:'N j, Y, P'(例如 Feb. 4, 2003, 4 p.m.)

用于在系统的任何部分显示日期时间字段的默认格式。 请注意,如果 :setting:`USE_L10N` 设置为 True,则语言环境指定的格式具有更高的优先级并将被应用。 看 :tfilter:`允许的日期格式字符串 ` .

另见 :setting:`DATE_FORMAT`:setting:`TIME_FORMAT`:setting:`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'
    '%Y-%m-%d',              # '2006-10-25'
    '%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',              # '10/25/2006'
    '%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'
    '%m/%d/%y',              # '10/25/06'
]

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

:setting:`USE_L10N`True 时,语言环境指定的格式具有更高的优先级,将改为应用。

另见 :setting:`DATE_INPUT_FORMATS`:setting:`TIME_INPUT_FORMATS`


DEBUG

默认值:False

打开/关闭调试模式的布尔值。

切勿在 :setting:`DEBUG` 打开的情况下将站点部署到生产环境中。

调试模式的主要功能之一是显示详细的错误页面。 如果您的应用程序在 :setting:`DEBUG`True 时引发异常,Django 将显示详细的回溯,包括很多关于您的环境的元数据,例如所有当前定义的 Django设置(来自 settings.py)。

作为一项安全措施,Django 将 包含可能敏感的设置,例如 :setting:`SECRET_KEY`。 具体来说,它将排除名称包含以下任何一项的任何设置:

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

请注意,这些是 部分 匹配。 'PASS' 也会匹配 PASSWORD,就像 'TOKEN' 也会匹配 TOKENIZED 等等。

不过,请注意,您的调试输出中总会有不适合公众使用的部分。 文件路径、配置选项等都会为攻击者提供有关您服务器的额外信息。

同样重要的是要记住,在打开 :setting:`DEBUG` 的情况下运行时,Django 会记住它执行的每个 SQL 查询。 这在您调试时很有用,但它会迅速消耗生产服务器上的内存。

最后,如果 :setting:`DEBUG`False,还需要正确设置 :setting:`ALLOWED_HOSTS` 设置。 如果不这样做,将导致所有请求都返回为“Bad Request (400)”。

笔记

默认的settings.py创建的文件 :djadmin:`django-admin startproject `DEBUG = True为了方便。


DEBUG_PROPAGATE_EXCEPTIONS

默认值:False

如果设置为 True,Django 对视图函数的异常处理(handler500,或调试视图 if :setting:`DEBUG`True)并且会跳过 500 个响应 (django.request) 的日志记录,并且异常会向上传播。

这对于某些测试设置很有用。 除非您希望 Web 服务器(而不是 Django)生成“内部服务器错误”响应,否则不应在实时站点上使用它。 在这种情况下,请确保您的服务器不会在响应中显示堆栈跟踪或其他敏感信息。


DECIMAL_SEPARATOR

默认值:'.'(点)

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

请注意,如果 :setting:`USE_L10N` 设置为 True,则语言环境指定的格式具有更高的优先级并将被应用。

另见 :setting:`NUMBER_GROUPING`:setting:`THOUSAND_SEPARATOR`:setting:`USE_THOUSAND_SEPARATOR`


DEFAULT_CHARSET

默认值:'utf-8'

如果未手动指定 MIME 类型,则用于所有 HttpResponse 对象的默认字符集。 在构造 Content-Type 标头时使用。


DEFAULT_EXCEPTION_REPORTER_FILTER

默认值:'django.views.debug.SafeExceptionReporterFilter'

如果尚未将任何内容分配给 HttpRequest 实例,则要使用的默认异常报告器过滤器类。 请参阅 过滤错误报告


DEFAULT_FILE_STORAGE

默认值:'django.core.files.storage.FileSystemStorage'

用于未指定特定存储系统的任何文件相关操作的默认文件存储类。 请参阅 管理文件


DEFAULT_FROM_EMAIL

默认值:'webmaster@localhost'

用于来自站点管理员的各种自动通信的默认电子邮件地址。 这不包括发送到 :setting:`ADMINS`:setting:`MANAGERS` 的错误消息; 为此,请参阅 :setting:`SERVER_EMAIL`


DEFAULT_INDEX_TABLESPACE

默认值:(空字符串)

如果后端支持,则用于未指定字段索引的默认表空间(请参阅 Tablespaces)。


DEFAULT_TABLESPACE

默认值:(空字符串)

如果后端支持,则用于未指定模型的默认表空间(请参阅 表空间 )。


DISALLOWED_USER_AGENTS

默认值:[](空列表)

表示不允许访问系统范围内任何页面的用户代理字符串的已编译正则表达式对象列表。 将此用于机器人/爬虫。 这仅在安装了 CommonMiddleware 时使用(请参阅 中间件 )。


EMAIL_BACKEND

默认值:'django.core.mail.backends.smtp.EmailBackend'

用于发送电子邮件的后端。 有关可用后端的列表,请参阅 发送电子邮件


EMAIL_FILE_PATH

默认值:未定义

文件电子邮件后端 用于存储输出文件的目录。


EMAIL_HOST

默认值:'localhost'

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

另见 :setting:`EMAIL_PORT`


EMAIL_HOST_PASSWORD

默认值:(空字符串)

用于 :setting:`EMAIL_HOST` 中定义的 SMTP 服务器的密码。 当向 SMTP 服务器进行身份验证时,此设置与 :setting:`EMAIL_HOST_USER` 结合使用。 如果这些设置中的任何一个为空,Django 将不会尝试进行身份验证。

另见 :setting:`EMAIL_HOST_USER`


EMAIL_HOST_USER

默认值:(空字符串)

用于 :setting:`EMAIL_HOST` 中定义的 SMTP 服务器的用户名。 如果为空,Django 将不会尝试身份验证。

另见 :setting:`EMAIL_HOST_PASSWORD`


EMAIL_PORT

默认值:25

用于 :setting:`EMAIL_HOST` 中定义的 SMTP 服务器的端口。


EMAIL_SUBJECT_PREFIX

默认值:'[Django] '

使用 django.core.mail.mail_adminsdjango.core.mail.mail_managers 发送的电子邮件的主题行前缀。 您可能希望包括尾随空格。


EMAIL_USE_LOCALTIME

默认值:False

是否以本地时区 (True) 或 UTC (False) 发送电子邮件的 SMTP Date 标头。


EMAIL_USE_TLS

默认值:False

与 SMTP 服务器通话时是否使用 TLS(安全)连接。 这用于显式 TLS 连接,通常在端口 587 上。 如果您遇到挂起的连接,请参阅隐式 TLS 设置 :setting:`EMAIL_USE_SSL`


EMAIL_USE_SSL

默认值:False

与 SMTP 服务器通信时是否使用隐式 TLS(安全)连接。 在大多数电子邮件文档中,这种类型的 TLS 连接称为 SSL。 一般用于465端口。 如果您遇到问题,请参阅显式 TLS 设置 :setting:`EMAIL_USE_TLS`

请注意,:setting:`EMAIL_USE_TLS`/:setting:`EMAIL_USE_SSL` 是互斥的,因此只需将这些设置之一设置为 True


EMAIL_SSL_CERTFILE

默认值:None

如果 :setting:`EMAIL_USE_SSL`:setting:`EMAIL_USE_TLS`True,您可以选择指定要使用的 PEM 格式的证书链文件的路径用于 SSL 连接。


EMAIL_SSL_KEYFILE

默认值:None

如果 :setting:`EMAIL_USE_SSL`:setting:`EMAIL_USE_TLS`True,您可以选择指定要使用的 PEM 格式的私钥文件的路径用于 SSL 连接。

请注意,设置 :setting:`EMAIL_SSL_CERTFILE`:setting:`EMAIL_SSL_KEYFILE` 不会导致任何证书检查。 它们被传递到底层 SSL 连接。 关于如何处理证书链文件和私钥文件的详细信息,请参阅 Python 的 python:ssl.wrap_socket() 函数的文档。


EMAIL_TIMEOUT

默认值:None

指定阻塞操作(如连接尝试)的超时(以秒为单位)。


FILE_CHARSET

默认值:'utf-8'

用于解码从磁盘读取的任何文件的字符编码。 这包括模板文件、静态文件和翻译目录。

自 2.2 版起已弃用:此设置已弃用。 从 Django 3.1 开始,从磁盘读取的文件必须是 UTF-8 编码。


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

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

此设置还决定了使用 :djadmin:`collectstatic` 管理命令时收集的静态目录的默认权限。 有关覆盖它的详细信息,请参阅 :djadmin:`collectstatic`

该值反映了 :setting:`FILE_UPLOAD_PERMISSIONS` 设置的功能和注意事项。


FILE_UPLOAD_PERMISSIONS

默认值:0o644

数字模式(即 0o644) 将新上传的文件设置为。 有关这些模式含义的更多信息,请参阅 os.chmod() 的文档。

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

出于安全原因,这些权限不适用于存储在 :setting:`FILE_UPLOAD_TEMP_DIR` 中的临时文件。

此设置还决定了使用 :djadmin:`collectstatic` 管理命令时收集的静态文件的默认权限。 有关覆盖它的详细信息,请参阅 :djadmin:`collectstatic`

警告

总是在模式前缀 0o .

如果您不熟悉文件模式,请注意 0o 前缀非常重要:它表示一个八进制数,这是必须指定模式的方式。 如果您尝试使用 644,您将得到完全不正确的行为。


3.0 版本变化: 在旧版本中,默认值为None


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 目录之外,按搜索顺序搜索夹具文件的目录列表。

请注意,即使在 Windows 上,这些路径也应使用 Unix 样式的正斜杠。

请参阅 使用夹具提供数据夹具加载


FORCE_SCRIPT_NAME

默认值:None

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


FORM_RENDERER

默认值:'django.forms.renderers.DjangoTemplates'

呈现表单小部件的类。 它必须实现 低级渲染 API


FORMAT_MODULE_PATH

默认值:None

包含项目语言环境的自定义格式定义的 Python 包的完整 Python 路径。 如果不是 None,Django 将在名为当前语言环境的目录下检查 formats.py 文件,并将使用该文件中定义的格式。

例如,如果 :setting:`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 路径,直到找到一个实际定义给定格式的模块。 这意味着列表中较靠前的包中定义的格式将优先于较靠后的包中的相同格式。

可用的格式有:


IGNORABLE_404_URLS

默认值:[](空列表)

描述通过电子邮件报告 HTTP 404 错误时应忽略的 URL 的已编译正则表达式对象列表(请参阅 错误报告 )。 正则表达式匹配 request' 的完整路径 (包括查询字符串,如果有的话)。 如果您的站点不提供常见请求的文件,例如 favicon.icorobots.txt,请使用此选项。

这仅在启用 BrokenLinkEmailsMiddleware 时使用(参见 Middleware)。


INSTALLED_APPS

默认值:[](空列表)

指定在此 Django 安装中启用的所有应用程序的字符串列表。 每个字符串应该是一个带点的 Python 路径:

  • 应用程序配置类(首选),或
  • 包含应用程序的包。

详细了解应用配置

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

你的代码永远不应该直接访问 :setting:`INSTALLED_APPS`。 改用 django.apps.apps


应用程序名称和标签在 :setting:`INSTALLED_APPS` 中必须是唯一的

Application names — 应用程序包的虚线 Python 路径 — 必须是唯一的。 没有办法将同一个应用程序包含两次,除非以另一个名称复制其代码。

应用程序 labels - 默认情况下名称的最后一部分 - 也必须是唯一的。 例如,您不能同时包含 django.contrib.authmyproject.auth。 但是,您可以使用定义不同 标签 的自定义配置重新标记应用程序。

无论 :setting:`INSTALLED_APPS` 是引用应用程序配置类还是应用程序包,这些规则都适用。


当多个应用程序提供相同资源(模板、静态文件、管理命令、翻译)的不同版本时,:setting:`INSTALLED_APPS` 中首先列出的应用程序具有优先权。


INTERNAL_IPS

默认值:[](空列表)

作为字符串的 IP 地址列表:

  • 允许 debug() 上下文处理器向模板上下文添加一些变量。
  • 即使没有以员工用户身份登录,也可以使用 admindocs 书签
  • AdminEmailHandler 电子邮件中标记为“内部”(而不是“外部”)。


LANGUAGE_CODE

默认值:'en-us'

表示此安装的语言代码的字符串。 这应该是标准的 语言 ID 格式 。 例如,美国 英文是"en-us"。 另请参阅 语言标识符列表国际化和本地化

:setting:`USE_I18N` 必须处于活动状态才能使此设置生效。

它有两个目的:

  • 如果没有使用语言环境中间件,它会决定为所有用户提供哪种翻译。
  • 如果区域设置中间件处于活动状态,它会提供备用语言,以防用户的首选语言无法确定或网站不支持。 当用户首选语言不存在给定文字的翻译时,它还提供后备翻译。

有关更多详细信息,请参阅 Django 如何发现语言偏好


LANGUAGES

默认:所有可用语言的列表。 此列表在不断增长,包括此处的副本将不可避免地迅速过时。 您可以通过查看 :source:`django/conf/global_settings.py` 来查看当前的翻译语言列表。

该列表是格式为(语言代码language name)的二元组列表——例如,('ja', 'Japanese')。 这指定了哪些语言可用于语言选择。 参见 国际化和本地化

通常,默认值就足够了。 如果要将语言选择限制为 Django 提供的语言的子集,请仅设置此设置。

如果您定义自定义 :setting:`LANGUAGES` 设置,则可以使用 gettext_lazy() 函数将语言名称标记为翻译字符串。

这是一个示例设置文件:

from django.utils.translation import gettext_lazy as _

LANGUAGES = [
    ('de', _('German')),
    ('en', _('English')),
]

LANGUAGES_BIDI

默认值:从右到左书写的所有语言代码的列表。 您可以通过查看 :source:`django/conf/global_settings.py` 来查看这些语言的当前列表。

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

通常,默认值就足够了。 如果要将语言选择限制为 Django 提供的语言的子集,请仅设置此设置。 如果您定义自定义 :setting:`LANGUAGES` 设置,则双向语言列表可能包含在给定站点上未启用的语言代码。


LOCALE_PATHS

默认值:[](空列表)

Django 在其中查找翻译文件的目录列表。 请参阅 Django 如何发现翻译

例子:

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

Django 将在这些路径中的每一个中查找包含实际翻译文件的 <locale_code>/LC_MESSAGES 目录。


LOGGING

默认值:日志配置字典。

包含配置信息的数据结构。 该数据结构的内容将作为参数传递给 :setting:`LOGGING_CONFIG` 中描述的配置方法。

除其他外,当 :setting:`DEBUG`False 时,默认日志记录配置会将 HTTP 500 服务器错误传递给电子邮件日志处理程序。 另请参阅 配置日志记录

您可以通过查看 :source:`django/utils/log.py` 来查看默认日志配置。


LOGGING_CONFIG

默认值:'logging.config.dictConfig'

将用于在 Django 项目中配置日志记录的可调用文件的路径。 默认情况下指向 Python 的 dictConfig 配置方法的实例。

如果将 :setting:`LOGGING_CONFIG` 设置为 None,将跳过日志配置过程。


MANAGERS

默认值:[](空列表)

:setting:`ADMINS` 格式相同的列表,指定在启用 BrokenLinkEmailsMiddleware 时谁应该收到断开的链接通知。


MEDIA_ROOT

默认值:(空字符串)

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

示例:"/var/www/example.com/media/"

另见 :setting:`MEDIA_URL`

警告

:setting:`MEDIA_ROOT`:setting:`STATIC_ROOT` 必须有不同的值。 在引入 :setting:`STATIC_ROOT` 之前,通常依赖或回退 :setting:`MEDIA_ROOT` 来提供静态文件; 但是,由于这可能具有严重的安全隐患,因此需要进行验证检查以防止它发生。


MEDIA_URL

默认值:(空字符串)

处理从 :setting:`MEDIA_ROOT` 提供的媒体的 URL,用于 管理存储的文件 。 如果设置为非空值,它必须以斜杠结尾。 您将需要 配置这些文件以在开发和生产环境中使用

如果要在模板中使用 模板:MEDIA URL,请在 :setting:`TEMPLATES`'context_processors' 选项中添加 'django.template.context_processors.media'

示例:"http://media.example.com/%22

警告

如果您接受来自不受信任用户的上传内容,则存在安全风险! 有关缓解详细信息,请参阅有关 用户上传的内容 的安全指南主题。


警告

:setting:`MEDIA_URL`:setting:`STATIC_URL` 必须有不同的值。 有关更多详细信息,请参阅 :setting:`MEDIA_ROOT`


MIDDLEWARE

默认值:None

要使用的中间件列表。 请参阅 中间件


MIGRATION_MODULES

默认值:{}(空字典)

一个字典,指定可以在每个应用程序的基础上找到迁移模块的包。 此设置的默认值为空字典,但迁移模块的默认包名称为 migrations

例子:

{'blog': 'blog.db_migrations'}

在这种情况下,与 blog 应用程序相关的迁移将包含在 blog.db_migrations 包中。

如果您提供 app_label 参数,:djadmin:`makemigrations` 将自动创建该包(如果该包不存在)。

当您提供 None 作为应用程序的值时,Django 会将应用程序视为没有迁移的应用程序,而不管现有的 migrations 子模块如何。 例如,这可以在测试设置文件中用于在测试时跳过迁移(仍将为应用程序模型创建表)。 如果这在您的常规项目设置中使用,如果您想为应用程序创建表,请记住使用 migrate --run-syncdb 选项。


MONTH_DAY_FORMAT

默认值:'F j'

在 Django 管理更改列表页面上用于日期字段的默认格式 – 也可能由系统的其他部分 – 在仅显示月份和日期的情况下。

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

请注意,如果 :setting:`USE_L10N` 设置为 True,则相应的区域指定格式具有更高的优先级并将被应用。

:tfilter:`允许的日期格式字符串 ` . 另见 :setting:`DATE_FORMAT`, :setting:`DATETIME_FORMAT`, :setting:`TIME_FORMAT`:setting:`YEAR_MONTH_FORMAT`


NUMBER_GROUPING

默认值:0

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

常见用途是显示千位分隔符。 如果此设置为 0,则不会对该号码应用任何分组。 如果此设置大于 0,则 :setting:`THOUSAND_SEPARATOR` 将用作这些组之间的分隔符。

一些语言环境使用非统一的数字分组,例如 en_IN 中的 10,00,00,000。 对于这种情况,您可以提供一个包含要应用的数字组大小数量的序列。 第一个数字定义十进制分隔符前面的组的大小,后面的每个数字定义前面组的大小。 如果序列以 -1 结束,则不会执行进一步的分组。 如果序列以 0 结尾,则最后一个组大小用于编号的其余部分。

en_IN 的示例元组:

NUMBER_GROUPING = (3, 2, 0)

请注意,如果 :setting:`USE_L10N` 设置为 True,则语言环境指定的格式具有更高的优先级并将被应用。

另见 :setting:`DECIMAL_SEPARATOR`:setting:`THOUSAND_SEPARATOR`:setting:`USE_THOUSAND_SEPARATOR`


PREPEND_WWW

默认值:False

是否在前面加上“www”。 子域到没有它的 URL。 这仅在安装了 CommonMiddleware 时使用(参见 Middleware)。 另见 :setting:`APPEND_SLASH`


ROOT_URLCONF

默认值:未定义

表示根 URLconf 的完整 Python 导入路径的字符串,例如 "mydjangoapps.urls"。 通过在传入的 HttpRequest 对象上设置属性 urlconf,可以在每个请求的基础上覆盖。 有关详细信息,请参阅 Django 如何处理请求


SECRET_KEY

默认值:(空字符串)

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

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

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

如果 :setting:`SECRET_KEY` 未设置,Django 将拒绝启动。

警告

将此值保密。

使用已知的 :setting:`SECRET_KEY` 运行 Django 会破坏 Django 的许多安全保护,并可能导致权限提升和远程代码执行漏洞。


密钥用于:

如果您轮换您的密钥,上述所有内容都将失效。 密钥不用于用户的密码,密钥轮换不会影响它们。

笔记

默认的settings.py创建的文件 :djadmin:`django-admin startproject ` 创造了一个独特的SECRET_KEY为了方便。


SECURE_BROWSER_XSS_FILTER

默认值:False

如果TrueSecurityMiddleware设置X-XSS-Protection:1; mode=block 在所有还没有它的响应上的标头。

现代浏览器不再支持 X-XSS-Protection HTTP 标头。 尽管该设置几乎没有什么实际好处,但如果您支持旧浏览器,您可能仍然希望设置标题。


SECURE_CONTENT_TYPE_NOSNIFF

默认值:True

如果 True,则 SecurityMiddleware 会在所有尚未拥有的响应上设置 X-Content-Type-Options: nosniff 标头。

3.0 版本变化: 在旧版本中,默认值为False


SECURE_HSTS_INCLUDE_SUBDOMAINS

默认值:False

如果是 True,则 SecurityMiddlewareincludeSubDomains 指令添加到 HTTP Strict Transport Security 标头。 除非 :setting:`SECURE_HSTS_SECONDS` 设置为非零值,否则它无效。

警告

不正确的设置会不可逆转地(对于 :setting:`SECURE_HSTS_SECONDS` 的值)破坏您的站点。 首先阅读 HTTP 严格传输安全 文档。


SECURE_HSTS_PRELOAD

默认值:False

如果是 True,则 SecurityMiddlewarepreload 指令添加到 HTTP Strict Transport Security 标头。 除非 :setting:`SECURE_HSTS_SECONDS` 设置为非零值,否则它无效。


SECURE_HSTS_SECONDS

默认值:0

如果设置为非零整数值,SecurityMiddleware 会在所有尚未拥有的响应上设置 HTTP Strict Transport Security 标头。

警告

设置不正确可能会不可逆转地(在一段时间内)破坏您的网站。 首先阅读 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 - 即使对于最初通过 HTTP 发出的请求也是如此。

在这种情况下,请配置您的代理以设置一个自定义 HTTP 标头,该标头告诉 Django 请求是否通过 HTTPS 传入,并设置 SECURE_PROXY_SSL_HEADER 以便 Django 知道要查找的标头。

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

SECURE_PROXY_SSL_HEADER = ('HTTP_X_FORWARDED_PROTO', 'https')

这告诉 Django 信任来自我们代理的 X-Forwarded-Proto 标头,只要它的值为 'https',那么该请求就保证是安全的(即,它最初是通过 HTTPS 传入的) .

如果您控制您的代理或有其他保证它适当地设置/剥离此标头,您应该 only 设置此设置。

请注意,标头需要采用 request.META 使用的格式 - 全部大写,并且可能以 HTTP_ 开头。 (请记住,Django 会自动将 'HTTP_' 添加到 x-header 名称的开头,然后才能在 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/$', …]。 如果 :setting:`SECURE_SSL_REDIRECT`False,则此设置无效。


SECURE_REFERRER_POLICY

3.0 版中的新功能。


默认值:None

如果已配置,SecurityMiddleware 将所有响应的 Referrer Policy 标头设置为提供的值。


SECURE_SSL_HOST

默认值:None

如果一个字符串(例如 secure.example.com),所有 SSL 重定向都将定向到此主机而不是最初请求的主机(例如 www.example.com)。 如果 :setting:`SECURE_SSL_REDIRECT`False,则此设置无效。


SECURE_SSL_REDIRECT

默认值:False

如果是 True,则 SecurityMiddleware 所有非 HTTPS 请求重定向到 HTTPS(除了那些与 :setting:`SECURE_REDIRECT_EXEMPT` 中列出的正则表达式匹配的 URL) )。

笔记

如果将其转换为 True 会导致无限重定向,则可能意味着您的站点在代理后面运行,无法分辨哪些请求是安全的,哪些不是。 您的代理可能会设置一个标头来指示安全请求; 您可以通过找出该标头是什么并相应地配置 :setting:`SECURE_PROXY_SSL_HEADER` 设置来纠正问题。


SERIALIZATION_MODULES

默认值:未定义

包含序列化程序定义(以字符串形式提供)的模块字典,以该序列化类型的字符串标识符为键。 例如,要定义 YAML 序列化程序,请使用:

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

SERVER_EMAIL

默认值:'root@localhost'

错误消息来自的电子邮件地址,例如发送到 :setting:`ADMINS`:setting:`MANAGERS` 的电子邮件地址。

为什么我的电子邮件从不同的地址发送?

此地址仅用于错误消息。 不是send_mail()发送的普通电子邮件的地址; 为此,请参阅 :setting:`DEFAULT_FROM_EMAIL`


SHORT_DATE_FORMAT

默认值:'m/d/Y'(例如 12/31/2003)

可用于在模板上显示日期字段的可用格式。 请注意,如果 :setting:`USE_L10N` 设置为 True,则相应的区域指定格式具有更高的优先级并将被应用。 看 :tfilter:`允许的日期格式字符串 ` .

另见 :setting:`DATE_FORMAT`:setting:`SHORT_DATETIME_FORMAT`


SHORT_DATETIME_FORMAT

默认值:'m/d/Y P'(例如 12/31/2003 4 p.m.)

可用于在模板上显示日期时间字段的可用格式。 请注意,如果 :setting:`USE_L10N` 设置为 True,则相应的区域指定格式具有更高的优先级并将被应用。 看 :tfilter:`允许的日期格式字符串 ` .

另见 :setting:`DATE_FORMAT`:setting:`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')。


NAME

默认值:见下文

此特定模板引擎的别名。 它是一个标识符,允许选择渲染引擎。 别名在所有配置的模板引擎中必须是唯一的。

它默认为定义引擎类的模块的名称,即 倒数第二块 :设置:`后端 ` ,当它没有提供时。 例如,如果后端是 'mypackage.whatever.Backend',那么它的默认名称是 'whatever'


DIRS

默认值:[](空列表)

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


APP_DIRS

默认值:False

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

笔记

默认的settings.py创建的文件 :djadmin:`django-admin startproject `'APP_DIRS': True .


OPTIONS

默认值:{}(空字典)

传递给模板后端的额外参数。 可用参数因模板后端而异。 有关内置后端的选项,请参阅 DjangoTemplatesJinja2


TEST_RUNNER

默认值:'django.test.runner.DiscoverRunner'

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


TEST_NON_SERIALIZED_APPS

默认值:[](空列表)

为了在 TransactionTestCase 测试和没有事务的数据库后端之间恢复数据库状态,Django 将 在开始测试运行时序列化所有应用程序 的内容,以便它可以从那里重新加载在运行需要它的测试之前复制。

这会减慢测试运行器的启动时间; 如果您知道您有不需要此功能的应用程序,您可以在此处添加它们的全名(例如 'django.contrib.contenttypes') 将它们排除在此序列化过程之外。


THOUSAND_SEPARATOR

默认值:','(逗号)

格式化数字时使用的默认千位分隔符。 此设置仅在 :setting:`USE_THOUSAND_SEPARATOR`True:setting:`NUMBER_GROUPING` 大于 0 时使用。

请注意,如果 :setting:`USE_L10N` 设置为 True,则语言环境指定的格式具有更高的优先级并将被应用。

另见 :setting:`NUMBER_GROUPING`:setting:`DECIMAL_SEPARATOR`:setting:`USE_THOUSAND_SEPARATOR`


TIME_FORMAT

默认值:'P'(例如 4 p.m.)

用于在系统的任何部分显示时间字段的默认格式。 请注意,如果 :setting:`USE_L10N` 设置为 True,则语言环境指定的格式具有更高的优先级并将被应用。 看 :tfilter:`允许的日期格式字符串 ` .

另见 :setting:`DATE_FORMAT`:setting:`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 模块语法 ,而不是来自 :tfilter:`date` 模板过滤器的格式字符串。

:setting:`USE_L10N`True 时,语言环境指定的格式具有更高的优先级,将改为应用。

另见 :setting:`DATE_INPUT_FORMATS`:setting:`DATETIME_INPUT_FORMATS`


TIME_ZONE

默认值:'America/Chicago'

表示此安装的时区的字符串。 请参阅 时区列表

笔记

由于 Django 首次发布时 :setting:`TIME_ZONE` 设置为 'America/Chicago',全局设置(如果在项目的 settings.py 中没有定义任何内容,则使用)仍然是 'America/Chicago' 向后兼容。 新项目模板默认为 'UTC'


请注意,这不一定是服务器的时区。 例如,一台服务器可能为多个 Django 驱动的站点提供服务,每个站点都有单独的时区设置。

:setting:`USE_TZ`False 时,这是 Django 将存储所有日期时间的时区。 当 :setting:`USE_TZ`True 时,这是 Django 将用于在模板中显示日期时间和解释在表单中输入的日期时间的默认时区。

在 Unix 环境中(其中实现了 time.tzset()),Django 将 os.environ['TZ'] 变量设置为您在 :setting:`TIME_ZONE` 设置中指定的时区。 因此,您的所有视图和模型都将在此时区自动运行。 但是,如果您使用 手动配置设置 中所述的手动配置选项,Django 将不会设置 TZ 环境变量。 如果 Django 没有设置 TZ 环境变量,则由您来确保您的进程在正确的环境中运行。

笔记

Django 无法在 Windows 环境中可靠地使用备用时区。 如果您在 Windows 上运行 Django,则 :setting:`TIME_ZONE` 必须设置为匹配系统时区。


USE_I18N

默认值:True

一个布尔值,指定是否应启用 Django 的翻译系统。 这提供了一种关闭它的方法,以提高性能。 如果设置为 False,Django 会做一些优化,以免加载翻译机器。

另见 :setting:`LANGUAGE_CODE`:setting:`USE_L10N`:setting:`USE_TZ`

笔记

默认的settings.py创建的文件 :djadmin:`django-admin startproject ` 包括USE_I18N = True为了方便。


USE_L10N

默认值:False

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

另见 :setting:`LANGUAGE_CODE`:setting:`USE_I18N`:setting:`USE_TZ`

笔记

默认的settings.py创建的文件 :djadmin:`django-admin startproject ` 包括USE_L10N = True为了方便。


USE_THOUSAND_SEPARATOR

默认值:False

一个布尔值,指定是否使用千位分隔符显示数字。 当设置为 True:setting:`USE_L10N` 也是 True 时,Django 将使用 :setting:`NUMBER_GROUPING`:setting:`THOUSAND_SEPARATOR` 设置。 这些设置也可能由优先的区域设置决定。

另见 :setting:`DECIMAL_SEPARATOR`:setting:`NUMBER_GROUPING`:setting:`THOUSAND_SEPARATOR`


USE_TZ

默认值:False

一个布尔值,指定日期时间是否默认时区感知。 如果设置为 True,Django 将在内部使用时区感知日期时间。 否则,Django 将使用本地时间的原始日期时间。

另见 :setting:`TIME_ZONE`:setting:`USE_I18N`:setting:`USE_L10N`

笔记

默认的settings.py创建的文件 :djadmin:`django-admin startproject ` 包括USE_TZ = True为了方便。


USE_X_FORWARDED_HOST

默认值:False

一个布尔值,指定是否优先使用 X-Forwarded-Host 标头而不是 Host 标头。 仅当使用设置此标头的代理时才应启用此功能。

此设置优先于 :setting:`USE_X_FORWARDED_PORT`。 根据 RFC 7239#section-5.3X-Forwarded-Host 标头可以包含端口号,在这种情况下,您不应使用 :setting:`USE_X_FORWARDED_PORT `


USE_X_FORWARDED_PORT

默认值:False

一个布尔值,指定是否优先于 SERVER_PORT META 变量使用 X-Forwarded-Port 标头。 仅当使用设置此标头的代理时才应启用此功能。

:setting:`USE_X_FORWARDED_HOST` 优先于这个设置。


WSGI_APPLICATION

默认值:None

Django 内置服务器的 WSGI 应用程序对象的完整 Python 路径(例如 :djadmin:`runserver`) 将使用。 这 :djadmin:`django-admin startproject ` 管理命令将创建一个标准wsgi.py文件与application可在其中调用,并将此设置指向该设置application .

如果未设置,将使用 django.core.wsgi.get_wsgi_application() 的返回值。 在这种情况下,:djadmin:`runserver` 的行为将与以前的 Django 版本相同。


YEAR_MONTH_FORMAT

默认值:'F Y'

在 Django 管理更改列表页面上用于日期字段的默认格式 – 也可能由系统的其他部分 – 在仅显示年和月的情况下。

例如,当 Django 管理更改列表页面被日期钻取过滤时,给定月份的标题显示月份和年份。 不同的地区有不同的格式。 例如,美国 英语会说“January 2006”,而另一个语言环境可能会说“2006/January”。

请注意,如果 :setting:`USE_L10N` 设置为 True,则相应的区域指定格式具有更高的优先级并将被应用。

:tfilter:`允许的日期格式字符串 ` . 另见 :setting:`DATE_FORMAT`, :setting:`DATETIME_FORMAT`, :setting:`TIME_FORMAT`:setting:`MONTH_DAY_FORMAT`


X_FRAME_OPTIONS

默认值:'DENY'

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

3.0 版本变化: 在旧版本中,默认值为SAMEORIGIN


认证

django.contrib.auth 的设置。

AUTHENTICATION_BACKENDS

默认值:['django.contrib.auth.backends.ModelBackend']

尝试对用户进行身份验证时要使用的身份验证后端类列表(作为字符串)。 有关详细信息,请参阅 身份验证后端文档


AUTH_USER_MODEL

默认值:'auth.User'

用于表示用户的模型。 请参阅 替换自定义用户模型

警告

您不能在项目的生命周期内更改 AUTH_USER_MODEL 设置(即 一旦您制作并迁移了依赖于它的模型)而无需付出任何努力。 它旨在在项目开始时设置,并且它所引用的模型必须在它所在的应用程序的第一次迁移中可用。 有关更多详细信息,请参阅 替换自定义用户模型


LOGIN_REDIRECT_URL

默认值:'/accounts/profile/'

LoginView 没有获得 next GET 参数时,URL 或 命名的 URL 模式 请求在登录后重定向。


LOGIN_URL

默认值:'/accounts/login/'

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


LOGOUT_REDIRECT_URL

默认值:None

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

如果是 None,则不会执行重定向并呈现注销视图。


PASSWORD_RESET_TIMEOUT_DAYS

默认值: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',
]

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 的后端 - CookieStorageFallbackStorage - 使用 :setting:`SESSION_COOKIE_DOMAIN`, :setting:`SESSION_COOKIE18SEC8X] 的值] 和 :setting:`SESSION_COOKIE_HTTPONLY` 在设置他们的 cookie 时。


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_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.PickleSerializer'
  • 'django.contrib.sessions.serializers.JSONSerializer'

有关详细信息,请参阅 会话序列化 ,包括有关使用 PickleSerializer 时可能远程执行代码的警告。


网站

django.contrib.sites 的设置。

SITE_ID

默认值:未定义

django_site 数据库表中当前站点的 ID(整数)。 使用它是为了使应用程序数据可以连接到特定站点,并且单个数据库可以管理多个站点的内容。


静态文件

django.contrib.staticfiles 的设置。

STATIC_ROOT

默认值:None

:djadmin:`collectstatic` 将收集用于部署的静态文件的目录的绝对路径。

示例:"/var/www/example.com/static/"

如果启用了 staticfiles contrib 应用程序(如在默认项目模板中),则 :djadmin:`collectstatic` 管理命令会将静态文件收集到此目录中。 有关用法的更多详细信息,请参阅 管理静态文件 上的操作方法。

警告

这应该是一个最初为空的目标目录,用于将静态文件从其永久位置收集到一个目录中,以便于部署; 它是 不是 永久存储静态文件的地方。 您应该在可以通过以下方式找到的目录中执行此操作静态文件:设置:`发现者 ` ,默认情况下是'static/' app 子目录和您包含的任何目录 :设置:`STATICFILES_DIRS` )。


STATIC_URL

默认值:None

引用位于 :setting:`STATIC_ROOT` 中的静态文件时使用的 URL。

示例:"/static/""http://static.example.com/%22

如果不是 None,这将用作 资产定义Media 类)和 staticfiles 应用程序 的基本路径。

如果设置为非空值,它必须以斜杠结尾。

您可能需要 配置这些文件以在开发 中提供服务,并且在生产 中肯定需要这样做


STATICFILES_DIRS

默认值:[](空列表)

如果启用 FileSystemFinder 查找器,此设置定义 staticfiles 应用程序将遍历的其他位置,例如 如果您使用 :djadmin:`collectstatic`:djadmin:`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"),
]

例如,假设您将 :setting:`STATIC_URL` 设置为 '/static/':djadmin:`collectstatic` 管理命令将收集“stats”文件:setting:`STATIC_ROOT`'downloads' 子目录。

这将允许您在模板中使用 '/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'

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

可以在 django.contrib.staticfiles.storage.staticfiles_storage 中找到此设置中定义的存储后端的即用型实例。

有关示例,请参阅 从云服务或 CDN 提供静态文件。


STATICFILES_FINDERS

默认:

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

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

默认将查找存储在 :setting:`STATICFILES_DIRS` 设置(使用 django.contrib.staticfiles.finders.FileSystemFinder)和每个应用程序的 static 子目录(使用 django.contrib.staticfiles.finders.AppDirectoriesFinder ])。 如果存在多个同名文件,将使用找到的第一个文件。

默认禁用一个取景器:django.contrib.staticfiles.finders.DefaultStorageFinder。 如果添加到您的 :setting:`STATICFILES_FINDERS` 设置中,它将在 :setting:`DEFAULT_FILE_STORAGE` 设置定义的默认文件存储中查找静态文件。

笔记

使用 AppDirectoriesFinder 查找器时,通过将应用添加到您网站的 :setting:`INSTALLED_APPS` 设置,确保静态文件可以找到您的应用。


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


核心设置专题索引