【1】引言#

• Django的默认配置文件中，包含上百条配置项目
• 其中很多是我们‘一辈子’都不碰到或者不需要单独配置的
• 这些项目在需要的时候再去查手册。

【2】强调#

• 配置的默认值不是在settings.py文件中！
• 不要以为settings.py中的配置值就是默认值，参考前文。
• settings.py是使用django-admin startproject xxx命令时，额外给我们创建的。

ABSOLUTE_URL_OVERRIDES#

1
ABSOLUTE_URL_OVERRIDES = {
2
    'blogs.weblog': lambda o: "/blogs/%s/" % o.slug,
3
    'news.story': lambda o: "/stories/%s/%s/" % (o.pub_year, o.slug),
4
}

ADMINS#

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

ALLOWED_HOSTS#

APPEND_SLASH#

1
DATABASES = {
2
    'default': {
3
        'ENGINE': 'django.db.backends.sqlite3',
4
        'NAME': 'mydatabase',
5
        # 或者'NAME': os.path.join(BASE_DIR, 'db.sqlite3'),
6
    }
7
}

1
DATABASES = {
2
    'default': {
3
        'ENGINE': 'django.db.backends.postgresql',
4
        'NAME': 'mydatabase',
5
        'USER': 'mydatabaseuser',
6
        'PASSWORD': 'mypassword',
7
        'HOST': '127.0.0.1',
8
        'PORT': '5432',
9
    }
10
}

1
'django.db.backends.postgresql'
2
'django.db.backends.mysql'
3
'django.db.backends.sqlite3'
4
'django.db.backends.oracle'

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

1
DATABASES = {
2
    'default': {
3
        'ENGINE': 'django.db.backends.postgresql',
4
        'USER': 'mydatabaseuser',
5
        'NAME': 'mydatabase',
6
        'TEST': {
7
            'NAME': 'mytestdatabase',
8
        },
9
    },
10
}

DATE_INPUT_FORMATS#

• 默认值：

1
[
2
    '%Y-%m-%d', '%m/%d/%Y', '%m/%d/%y', # '2006-10-25', '10/25/2006', '10/25/06'
3
    '%b %d %Y', '%b %d, %Y',            # 'Oct 25 2006', 'Oct 25, 2006'
4
    '%d %b %Y', '%d %b, %Y',            # '25 Oct 2006', '25 Oct, 2006'
5
    '%B %d %Y', '%B %d, %Y',            # 'October 25 2006', 'October 25, 2006'
6
    '%d %B %Y', '%d %B, %Y',            # '25 October 2006', '25 October, 2006'
7
]

• 日期字段中输入数据时将能够被接受的格式列表。格式将按顺序尝试，使用第一个有效的格式。

1
[
2
    '%Y-%m-%d %H:%M:%S',     # '2006-10-25 14:30:59'
3
    '%Y-%m-%d %H:%M:%S.%f',  # '2006-10-25 14:30:59.000200'
4
    '%Y-%m-%d %H:%M',        # '2006-10-25 14:30'
5
    '%m/%d/%Y %H:%M:%S',     # '10/25/2006 14:30:59'
6
    '%m/%d/%Y %H:%M:%S.%f',  # '10/25/2006 14:30:59.000200'
7
    '%m/%d/%Y %H:%M',        # '10/25/2006 14:30'
8
    '%m/%d/%y %H:%M:%S',     # '10/25/06 14:30:59'
9
    '%m/%d/%y %H:%M:%S.%f',  # '10/25/06 14:30:59.000200'
10
    '%m/%d/%y %H:%M',        # '10/25/06 14:30'
11
]

DEBUG#

1
'API'
2
'KEY'
3
'PASS'
4
'SECRET'
5
'SIGNATURE'
6
'TOKEN'

DEBUG_PROPAGATE_EXCEPTIONS#

• 默认值：False
• 如果设置为True，Django的异常处理视图和500响应日志将被忽略，并向上传播异常。常用于测试工作。

DECIMAL_SEPARATOR#

• 默认值：圆点.
• 指定用于分隔数字的符号。

DEFAULT_CHARSET#

• 默认值：‘utf-8’
• HttpResponse响应对象的默认字符集。

DEFAULT_EXCEPTION_REPORTER#

• 默认值：‘django.views.debug.ExceptionReporter’
• 配置默认的异常报告器。Django3.1新增。

DEFAULT_EXCEPTION_REPORTER_FILTER#

• 默认值: ‘django.views.debug.SafeExceptionReporterFilter’
• 配置默认的异常报告过滤器。Django3.1新增。

DEFAULT_FILE_STORAGE#

• 默认值: ‘django.core.files.storage.FileSystemStorage’
• 默认的文件管理存储器。

DEFAULT_FROM_EMAIL#

• 默认值：‘webmaster@localhost’
• 默认的电子邮件发送地址，即发送方。

DEFAULT_INDEX_TABLESPACE#

• 默认值：空字符串
• 默认用于字段上的索引的表空间。

DEFAULT_TABLESPACE#

• 默认值：空字符串
• 自定模型的表空间。

DISALLOWED_USER_AGENTS#

EMAIL_BACKEND#

• 默认值：’ django.core.mail.backends.smtp.EmailBackend ’
• 用于发送邮件的后端。

EMAIL_FILE_PATH#

• 默认：未指定
• 邮件后端保存输出文件时使用的目录。支持pathlib.Path

EMAIL_HOST#

• 默认：‘localhost’
• 发送邮件使用的主机。

EMAIL_HOST_PASSWORD#

• 默认值：”（空字符串）
• EMAIL_HOST的SMTP服务器使用的密码。

EMAIL_HOST_USER#

• 默认值：”（空字符串）
• EMAIL_HOST的SMTP服务器使用的用户名。

EMAIL_PORT#

• 默认：25
• EMAIL_HOST的SMTP服务器使用的端口。

EMAIL_SUBJECT_PREFIX#

• 默认值：‘[Django] ’
• 使用django.core.mail.mail_admins或django.core.mail.mail_managers发送的电子邮件的主题行前缀。

EMAIL_USE_LOCALTIME#

• 默认值：False
• 邮件中是否使用本地时间。

EMAIL_USE_TLS#

• 默认值：False
• 是否使用TLS(安全)与SMTP服务器连接。用于显式TLS连接,通常在端口587上。

EMAIL_USE_SSL#

• 默认值：False
• 在与SMTP服务器通信时是否使用隐式TLS（安全）连接。在大多数电子邮件文档中，此类型的TLS连接称为SSL。 它通常在端口465上使用。
• 注意：腾讯家的qq邮箱服务，需要使用ssl安全链接在465端口上！
• 请注意，EMAIL_USE_TLS与EMAIL_USE_SSL是互斥的，因此只能将其中一个设置设置为True。

EMAIL_SSL_CERTFILE#

• 默认值：None
• 如果EMAIL_USE_SSL或EMAIL_USE_TLS为True，则可以选择指定要用于SSL连接的PEM格式的证书链文件的路径。

EMAIL_SSL_KEYFILE#

• 默认值：None
• 如果EMAIL_USE_SSL或EMAIL_USE_TLS为True，可以选择指定要用于SSL连接的PEM格式的私钥文件的路径。

EMAIL_TIMEOUT#

• 默认值：None
• 邮件发送超时时间。

FILE_UPLOAD_HANDLERS#

• 默认:

1
[
2
    'django.core.files.uploadhandler.MemoryFileUploadHandler',
3
    'django.core.files.uploadhandler.TemporaryFileUploadHandler',
4
]

• 用于处理上传文件的处理器。

FILE_UPLOAD_MAX_MEMORY_SIZE#

• 默认值: 2621440 (2.5 MB).
• 允许上传文件的最大的字节数，否则将以流模式进行。

FILE_UPLOAD_DIRECTORY_PERMISSIONS#

• 默认值: None
• 上传目录的权限设置，以775类似的数字形式表示。

FILE_UPLOAD_PERMISSIONS#

• Default: 0o644
• 上传文件的权限设置，以0o644类似的数字形式表示。

FILE_UPLOAD_TEMP_DIR#

• 默认值: None
• 临时储存文件的目录。
• FIRST_DAY_OF_WEEK
• 默认为：0（星期天）
• 数字形式表示，用于设置每周第一天是哪天。
• 值0-6，0表示星期天，1表示星期一，6表示星期六。

FORM_RENDERER#

默认值：‘django.forms.renderers.DjangoTemplates’

指定用于渲染表单widgets的渲染类。

INSTALLED_APPS#

1
INSTALLED_APPS = [
2
    'django.contrib.admin',
3
    'django.contrib.auth',
4
    'django.contrib.contenttypes',
5
    'django.contrib.sessions',
6
    'django.contrib.messages',
7
    'django.contrib.staticfiles',
8
    'app1',
9
    'app2',
10
]

LANGUAGE_CODE#

LANGUAGES#

1
from django.utils.translation import ugettext_lazy as _
2

3
LANGUAGES = [
4
    ('de', _('German')),
5
    ('en', _('English')),
6
]

LOCALE_PATHS#

• 默认值：[]（空列表）
• Django查找翻译文件的目录列表,例如：

1
LOCALE_PATHS = [
2
    '/home/www/project/common_files/locale',
3
    '/var/local/translations/locale',
4
]

• Django将在这些路径中查找包含实际翻译文件的目录。

LOGGING#

• 默认值：日志配置字典。
• 日志配置信息。

LOGGING_CONFIG#

• 默认值：‘logging.config.dictConfig’
• 用于在Django项目中配置日志记录的可调用项的路径。

MEDIA_ROOT#

MEDIA_URL#

MIDDLEWARE#

• 默认值：None
• 要使用的中间件列表。
• Django-admin命令创建的新项目中，settings.py文件里默认会为MIDDLEWARE配置项添加一系列Django内置的中间件，我们保持它不变就好了。

PREPEND_WWW#

• 默认值：False
• 是否自动为URL添加www.的域名前缀。
• 只有在CommonMiddleware中间件启用后，才可以打开这个功能。

SECRET_KEY#

• 默认值：”（空字符串）
• 当前Django项目实例的密钥。用于提供cryptographic签名，是一个唯一的并且不可预测的值。比如：

1
SECRET_KEY = '+$*n1_pkko%zaz3!lm8lg208@uj^qy3mcsuy+*ov%ikpvd5$rf'

• 通过django-admin startproject xxx命令创建的项目，会在settings.py中添加随机生成的SECRET_KEY。
• 如果未设置SECRET_KEY，Django将无法启动。

警告：不要透露该配置项的真实值！

• 这个安全密钥主要用于：
  • 会话验证
  • 消息加密
  • 加密签名

SERVER_EMAIL#

• 默认值：‘root@localhost’
• 发送错误信息的邮件，邮件的发送方。

TEMPLATES#

• 默认值：[]（空列表）
• Django模板系统相关的配置。列表中每一项都是一个字典类型数据（类似DATABASE配置），可以配置模板不同的功能。
• 下面是一个例子：

1
TEMPLATES = [
2
    {
3
        'BACKEND': 'django.template.backends.django.DjangoTemplates',
4
        'APP_DIRS': True,
5
    },
6
]

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

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

THOUSAND_SEPARATOR#

• 默认值：逗号
• 千位分隔符。

TIME_FORMAT#

• 默认值: ‘P’ (e.g. 4 p.m.)
• 时间字段的默认显式格式

TIME_INPUT_FORMATS#

• 默认:

1
[
2
    '%H:%M:%S',     # '14:30:59'
3
    '%H:%M:%S.%f',  # '14:30:59.000200'
4
    '%H:%M',        # '14:30'
5
]

• 默认接收的时间格式

TIME_ZONE#

• 默认：‘America/Chicago’
• 时区设置。
• 注意，这个配置项的值不一定要和服务器的时区一致。例如，一个服务器可上可能有多个Django站点，每个站点都有一个单独的时区设置。
• 如果要设为中国时间，也就是北京时间，请赋值：TIME_ZONE = ‘Asia/Shanghai’。注意是上海，不是北京，囧！
• 当USE_TZ为False时，它将成为Django存储所有日期和时间数据时，使用的时区。 当USE_TZ为True 时，它是Django显示模板中的时间，解释表单中的日期，使用的时区。所以，通常我们都将USE_TZ同时设置为False！
• 注：在Windows 环境中，Django不能可靠地交替其它时区。如果你在Windows上运行Django，TIME_ZONE必须设置为与系统时区一致。

USE_I18N#

• 默认值：True
• 这是一个布尔值，指定Django的翻译系统是否开启。如果设置为False，Django会做一些优化，不去加载翻译机制。
• 由django-admin startproject xxx命令创建的Django项目，其settings.py文件中’USE_I18N’已经设置为True了。

USE_L10N#

• 默认值：False
• 一个布尔值，用于决定是否开启数据本地化。如果此设置为True，例如Django将使用当前语言环境的格式显示数字和日期。
• 由django-admin startproject xxx命令创建的Django项目，其settings.py文件中’USE_L10N’已经设置为True了。

USE_TZ#

• 默认值：False
• 一个布尔值,用来指定是否使用指定的时区(TIME_ZONE)的时间。若为True, 则Django会使用内建的时区的时间；否则, Django将会使用本地的时间。
• 由django-admin startproject xxx命令创建的Django项目，其settings.py文件中’USE_TZ’已经设置为True了。
• 如果我们将TIME_ZONE设置成了Asia/Shanghai， 那么务必同时将USE_TZ改成False！

WSGI_APPLICATION#

• 默认值：None
• Django的内置服务器（例如runserver）将使用的WSGI应用程序对象的完整Python路径。
• Django使用WSGI协议与外部进行通信。
• 由django-admin startproject xxx命令创建的Django项目，将自动创建一个简单的wsgi.py模块，里面有一个可调用的application变量，WSGI_APPLICATION配置项的值就指向这个application变量。
• 下面是wsgi.py的源码：

1
"""
2
WSGI config for mysite project.
3
It exposes the WSGI callable as a module-level variable named ``application``.
4
For more information on this file, see https://docs.djangoproject.com/en/1.11/howto/deployment/wsgi/
5
"""
6

7
import os
8

9
from django.core.wsgi import get_wsgi_application
10

11
os.environ.setdefault("DJANGO_SETTINGS_MODULE", "mysite.settings")
12

13
application = get_wsgi_application()

CACHES#

• 默认值：

1
{
2
    'default': {
3
        'BACKEND': 'django.core.cache.backends.locmem.LocMemCache',
4
    }
5
}

• 一个嵌套字典，包含所有缓存系统要使用的设置。
• CACHES设置必须配置一个default缓存，还可以同时指定任何数量的附加缓存（也可以没有）。
• 以下是重要的内部配置项目：

1
'django.core.cache.backends.db.DatabaseCache'
2
'django.core.cache.backends.dummy.DummyCache'
3
'django.core.cache.backends.filebased.FileBasedCache'
4
'django.core.cache.backends.locmem.LocMemCache'
5
'django.core.cache.backends.memcached.MemcachedCache'
6
'django.core.cache.backends.memcached.PyLibMCCache'

1
CACHES = {
2
    'default': {
3
        'BACKEND': 'django.core.cache.backends.filebased.FileBasedCache',
4
        'LOCATION': '/var/tmp/django_cache',
5
    }
6
}

AUTHENTICATION_BACKENDS#

• 默认值：[‘django.contrib.auth.backends.ModelBackend’]
• 在尝试验证用户时使用的认证后端的列表。默认使用Django自带的Auth框架。

AUTH_USER_MODEL#

• 默认值：‘auth.User’
• 指定项目使用的真正User模型。
• 这个配置在认证和权限管理中非常重要！

LOGIN_REDIRECT_URL#

• 默认：‘/accounts/profile/’
• 登录之后，如果contrib.auth.login视图找不到next参数，请求将被重定向到该URL。

LOGIN_URL#

• 默认：‘/accounts/login/’
• 登录页面的URL。

LOGOUT_REDIRECT_URL#

• 默认值：None
• 使用LogoutView视图退出登录后，请求被重定向的URL。如果设置为None，则不执行重定向。

PASSWORD_RESET_TIMEOUT#

• Django3.1新增
• 默认值：259200（3天的总秒数）
• 密码重置链接的有效时间。用于PasswordResetConfirmView视图。

PASSWORD_HASHERS#

• 密码哈希使用的算法。
• 默认：

1
[
2
    'django.contrib.auth.hashers.PBKDF2PasswordHasher',
3
    'django.contrib.auth.hashers.PBKDF2SHA1PasswordHasher',
4
    'django.contrib.auth.hashers.Argon2PasswordHasher',
5
    'django.contrib.auth.hashers.BCryptSHA256PasswordHasher',
6
]

AUTH_PASSWORD_VALIDATORS#

• 默认值：空列表
• 用于检查密码强度的验证器的列表。

MESSAGE_LEVEL#

• 默认值：messages.INFO
• 设置Django内置的消息框架-message，将记录的最低消息级别。

MESSAGE_STORAGE#

• 默认值：‘django.contrib.messages.storage.fallback.FallbackStorage’
• 控制Django在哪里存储消息数据。 有效值为：

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

MESSAGE_TAGS#

• 默认:

1
{
2
    messages.DEBUG: 'debug',
3
    messages.INFO: 'info',
4
    messages.SUCCESS: 'success',
5
    messages.WARNING: 'warning',
6
    messages.ERROR: 'error',
7
}

• 消息级别和消息短符之间的映射关系。

SESSION_CACHE_ALIAS#

• 默认值: ‘default’
• 如果你在使用基于缓存的会话系统，这个配置项用于指定你要使用的缓存是哪个。

SESSION_COOKIE_AGE#

• 默认：1209600（2个星期）
• 会话Cookie的过期时间，以秒为单位。

SESSION_COOKIE_DOMAIN#

• 默认值: None
• 会话cookie使用的域名。

SESSION_COOKIE_HTTPONLY#

• 默认值: True
• 如果为True，表示只允许HTTP协议访问cookie，JS语言不可以。

SESSION_COOKIE_NAME#

• 默认值：‘sessionid’
• 要用于会话的Cookie的名称。 名字随意，只要与应用程序中的其他cookie名称不同。

SESSION_COOKIE_PATH#

• 默认： ’/’
• 在会话Cookie上设置的路径。
• 如果你有多个以相同主机名运行的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为默认值。

SESSION_COOKIE_SECURE#

• 默认值：False
• 是否对会话cookie使用加密连接。如果将其设置为 True，则意味着浏览器仅允许在HTTPS连接下发送cookie。

SESSION_ENGINE#

• 默认值：‘django.contrib.sessions.backends.db’
• 会话使用的后端，也就是会话数据的保存位置。默认保存在数据库中。
• 内置支持的引擎有：

1
'django.contrib.sessions.backends.db'
2
'django.contrib.sessions.backends.file'
3
'django.contrib.sessions.backends.cache'
4
'django.contrib.sessions.backends.cached_db'
5
'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’

SITE_ID#

• 默认：未指定
• 当前站点在django_site数据库表中的ID，一个整数，从1开始计数。
• 很多人都不知道Django是支持多站点同时运行的。
• 通常我们都只有一个站点，所以不关心这个选项。
• 如果你同时运行了多个站点，那么每个app就得知道自己是为那个站点或哪些站点服务的，这就需要SITE_ID参数了。

STATIC_ROOT#

• 默认值：None
• 在DEBUG设置为False时，也就是线上环境时，Django项目里的静态文件（js\css\plugins）会无法使用。
• 这时，需要运行python manage.py collectstatic，将静态文件统一收集到一个目录下。
• STATIC_ROOT配置的就是该目录的绝对路径。
• 示例：“/var/www/example.com/static/”
• 这个目录，刚开始应该是一个空目录。

STATIC_URL#

• 默认值：None
• 引用位于STATIC_ROOT中的静态文件时使用的网址。
• 示例：“/static/“或”http://static.example.com/”
• 该URL设置为非空值时，必须以斜杠“/”结束。

STATICFILES_DIRS#

• 默认值：[]（空列表）
• 定义额外的静态文件搜索地址。
• 例如：

1
STATICFILES_DIRS = [
2
    "/home/special.polls.com/polls/static",
3
    "/home/polls.com/polls/static",
4
    "/opt/webfiles/common",
5
]

• 请注意，即使在Windows上（例如”C:/Users/user/mysite/extra_static_content”），这些路径也要使用Unix样式的正斜杠。

• 如果你实在分不清楚MEDIA_ROOT、MEDIA_URL、STATIC_ROOT、STATIC_URL和STATICFILES_DIRS的区别，下面是一个参考版的设置:

1
from pathlib import Path
2

3
# Build paths inside the project like this: BASE_DIR / 'subdir'.
4
BASE_DIR = Path(__file__).resolve(strict=True).parent.parent
5

6
STATIC_URL = '/static/'
7
STATICFILES_DIRS = [
8
    BASE_DIR / "static",
9
]
10
STATIC_ROOT = BASE_DIR / "all_static_files"
11

12

13
MEDIA_ROOT = BASE_DIR / 'media'
14
MEDIA_URL = '/media/'