Django 设置

Django 设置文件包含 Django 安装的所有配置。本文档解释了设置的工作原理以及哪些设置可用。

基础知识

设置文件只是一个带有模块级变量的 Python 模块。

以下是几个示例设置：

ALLOWED_HOSTS = ['www.example.com']
DEBUG = False
DEFAULT_FROM_EMAIL = 'webmaster@example.com'

笔记

如果将 :setting:`DEBUG` 设置为 False，还需要正确设置 :setting:`ALLOWED_HOSTS` 设置。

因为设置文件是一个 Python 模块，所以以下适用：

它不允许出现 Python 语法错误。
它可以使用正常的 Python 语法动态分配设置。例如：
```
MY_SETTING = [str(i) for i in range(30)]
```
它可以从其他设置文件导入值。

指定设置

DJANGO_SETTINGS_MODULE

当您使用 Django 时，您必须告诉它您正在使用哪些设置。通过使用环境变量 DJANGO_SETTINGS_MODULE 来执行此操作。

DJANGO_SETTINGS_MODULE 的值应该是 Python 路径语法，例如 mysite.settings。请注意，设置模块应位于 Python 导入搜索路径上。

django-admin 实用程序

使用 django-admin 时，您可以设置一次环境变量，也可以在每次运行该实用程序时显式传入设置模块。

示例（Unix Bash shell）：

export DJANGO_SETTINGS_MODULE=mysite.settings
django-admin runserver

示例（Windows 外壳）：

set DJANGO_SETTINGS_MODULE=mysite.settings
django-admin runserver

使用 --settings 命令行参数手动指定设置：

django-admin runserver --settings=mysite.settings

在服务器上 (mod_wsgi)

在您的实时服务器环境中，您需要告诉您的 WSGI 应用程序使用什么设置文件。用 os.environ 做到这一点：

import os

os.environ['DJANGO_SETTINGS_MODULE'] = 'mysite.settings'

阅读 Django mod_wsgi 文档以获取更多信息和 Django WSGI 应用程序的其他常见元素。

默认设置

如果不需要，Django 设置文件不必定义任何设置。每个设置都有一个合理的默认值。这些默认值存在于模块 django/conf/global_settings.py 中。

这是 Django 在编译设置中使用的算法：

从 global_settings.py 加载设置。
从指定的设置文件加载设置，必要时覆盖全局设置。

请注意，设置文件应不应从 global_settings 导入，因为那是多余的。

查看您更改了哪些设置

命令 python manage.py diffsettings 显示当前设置文件和 Django 默认设置之间的差异。

有关更多信息，请参阅 :djadmin:`diffsettings` 文档。

在 Python 代码中使用设置

在您的 Django 应用程序中，通过导入对象 django.conf.settings 来使用设置。例子：

from django.conf import settings

if settings.DEBUG:
    # Do something

请注意， django.conf.settings 不是一个模块——它是一个对象。因此无法导入单个设置：

from django.conf.settings import DEBUG  # This won't work.

另请注意，您的代码应而非从 global_settings 或您自己的设置文件导入。 django.conf.settings 抽象了默认设置和站点特定设置的概念；它提供了一个单一的界面。它还将使用设置的代码与您的设置位置分离。

在运行时更改设置

您不应在运行时更改应用程序中的设置。例如，不要在视图中执行此操作：

from django.conf import settings

settings.DEBUG = True   # Don't do this!

您应该分配给设置的唯一位置是在设置文件中。

安全

由于设置文件包含敏感信息，例如数据库密码，您应该尽一切努力限制对它的访问。例如，更改其文件权限，以便只有您和您的 Web 服务器的用户才能读取它。这在共享托管环境中尤为重要。

可用设置

有关可用设置的完整列表，请参阅设置参考。

创建您自己的设置

没有什么可以阻止您为自己的 Django 应用程序创建自己的设置，但请遵循以下准则：

设置名称必须全部大写。
不要重新发明一个已经存在的设置。

对于序列设置，Django 本身使用列表，但这只是一个约定。

使用设置而不设置 DJANGO_SETTINGS_MODULE

在某些情况下，您可能希望绕过 DJANGO_SETTINGS_MODULE 环境变量。例如，如果您单独使用模板系统，您可能不想设置指向设置模块的环境变量。

在这些情况下，您可以手动配置 Django 的设置。通过调用执行此操作：

django.conf.settings.configure(default_settings, **settings)

例子：

from django.conf import settings

settings.configure(DEBUG=True)

传递 configure() 任意数量的关键字参数，每个关键字参数代表一个设置及其值。每个参数名称应全部为大写，名称与上述设置相同。如果特定设置未传递给 configure() 并且稍后需要，Django 将使用默认设置值。

当您在较大的应用程序中使用框架的一部分时，以这种方式配置 Django 是最有必要的——实际上也是推荐的。

因此，当通过 settings.configure() 进行配置时，Django 不会对进程环境变量进行任何修改（请参阅 :setting:`TIME_ZONE` 的文档了解为什么通常会发生这种情况）。在这些情况下，假设您已经完全控制了您的环境。

自定义默认设置

如果您希望默认值来自 django.conf.global_settings 以外的其他地方，您可以传入一个提供默认设置的模块或类作为 default_settings 参数（或作为第一个位置参数）在对 configure() 的调用中。

在本例中，默认设置取自 myapp_defaults，而 :setting:`DEBUG` 设置设置为 True，而不管其在 [ X154X]：

from django.conf import settings
from myapp import myapp_defaults

settings.configure(default_settings=myapp_defaults, DEBUG=True)

以下示例使用 myapp_defaults 作为位置参数，是等效的：

settings.configure(myapp_defaults, DEBUG=True)

通常，您不需要以这种方式覆盖默认值。 Django 默认设置足够温和，您可以安全地使用它们。请注意，如果您确实传入了一个新的默认模块，它会完全替换 Django 默认值，因此您必须为您正在导入的代码中可能使用的每个可能的设置指定一个值。在 django.conf.settings.global_settings 中查看完整列表。

需要 configure() 或 DJANGO_SETTINGS_MODULE

如果您没有设置 DJANGO_SETTINGS_MODULE 环境变量，则在使用任何读取设置的代码之前，您必须调用 configure()。

如果不设置 DJANGO_SETTINGS_MODULE 也不调用 configure()，Django 将在第一次访问设置时引发 ImportError 异常。

如果你设置了 DJANGO_SETTINGS_MODULE，以某种方式访问设置值，then 调用 configure()，Django 将引发一个 RuntimeError 表明设置已经被配置。有一个用于此目的的属性：

例如：

from django.conf import settings
if not settings.configured:
    settings.configure(myapp_defaults, DEBUG=True)

此外，多次调用 configure() 或在访问任何设置后调用 configure() 也是错误的。

归结为：仅使用 configure() 或 DJANGO_SETTINGS_MODULE 之一。两者都不是，也不是。

“独立”Django 使用需要调用 django.setup()

如果您正在使用 Django“独立”的组件——例如，编写一个 Python 脚本来加载一些 Django 模板并呈现它们，或者使用 ORM 来获取一些数据——除了配置设置之外，您还需要一个步骤.

在您设置 DJANGO_SETTINGS_MODULE 或调用 configure() 后，您需要调用 django.setup() 来加载您的设置和填充 Django 的应用程序注册表。例如：

import django
from django.conf import settings
from myapp import myapp_defaults

settings.configure(default_settings=myapp_defaults, DEBUG=True)
django.setup()

# Now this script or any imported module can use any part of Django it needs.
from myapp import models

请注意，仅当您的代码真正独立时，才需要调用 django.setup()。当您的 Web 服务器或通过 django-admin 调用时，Django 会为您处理。

django.setup() 只能被调用一次。

因此，避免将可重用的应用程序逻辑放在独立脚本中，以便您必须从应用程序的其他地方的脚本导入。如果无法避免，请将 django.setup() 的调用放在 if 块中：

if __name__ == '__main__':
    import django
    django.setup()

也可以看看

设置参考: 包含核心和 contrib 应用程序设置的完整列表。

Django 设置 — Django 文档

目录