Django 配置

Django 的配置文件包含 Django 应用的所有配置项。本文档介绍配置是如何生效的，以及哪些设置项是可配置的。

基础

配置文件只是一个使用模块级变量的一个 Python 模块。

一组配置例子:

  1. ALLOWED_HOSTS = ["www.example.com"]
  2. DEBUG = False
  3. DEFAULT_FROM_EMAIL = "webmaster@example.com"

备注

如果你将 DEBUG 设置为 False，同时你需要正确的设置 ALLOWED_HOSTS。

因为配置文件是一个 Python 模块，所以要注意以下几项:

  • 不能有 Python 语法错误

  • 可以用 Python 语法实现动态配置，例如:

    1. MY_SETTING = [str(i) for i in range(30)]

  • 可以从其他配置文件中引入变量

指定配置文件

DJANGO_SETTINGS_MODULE

当你使用 Django 的时候，你必须告诉它你正在使用哪些设置。通过使用环境变量 DJANGO_SETTINGS_MODULE 来实现。

DJANGO_SETTINGS_MODULE 的值是一个符合 Python 语法的路径，例如 mysite.settings。要注意配置模块应位于 Python 的 import 搜索路径 中。

django-admin 工具

使用 django-admin 时，你可以一次性设定环境变量，也可以在运行此工具时，显式地传入配置模块。

Example (Unix Bash shell):

  1. export DJANGO_SETTINGS_MODULE=mysite.settings
  2. django-admin runserver

Example (Windows shell):

  1. set DJANGO_SETTINGS_MODULE=mysite.settings
  2. django-admin runserver

Use the --settings command-line argument to specify the settings manually:

  1. django-admin runserver --settings=mysite.settings

服务器端 (mode_wsgi)

在服务器环境下，要通知WSGI应用当前使用的是哪个配置文件，用到 os.environ:

  1. import os
  3. os.environ["DJANGO_SETTINGS_MODULE"] = "mysite.settings"

阅读 Django mod_wsgi 文档 了解更多关于 Django WSGI 应用的信息和常见设置。

默认配置

A Django settings file doesn’t have to define any settings if it doesn’t need to. Each setting has a sensible default value. These defaults live in the module django/conf/global_settings.py.

Django按如下算法编译配置模块:

  • 从 global_settings.py 中加载配置项。
  • 从指定的配置文件中加载配置项，覆盖对应的全局配置项。

注意: 配置文件中不要再重复引用 global_settings，因为这样做是多余的。

查看你已经更改了哪个配置项

命令 python manage.py diffsettings 显示当前配置文件与 Django 默认配置的差异。

想了解更多, 可以查看 diffsettings 文档.

在 Python 代码中使用 settings

在具体的Django应用中, 通过引入 django.conf.settings 使用配置, 例:

  1. from django.conf import settings
  3. if settings.DEBUG:
  4.     # Do something
  5.     ...

注意 django.conf.settings 并不是一个模块！— 而是一个对象！所以引入某个单独的设置项是不可能的:

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

还要注意 不应该 直接引入 global_settings 和你自己的配置文件。 django.conf.settings 整合了默认配置和网站指定配置，从而只提供一个接口读取配置。它也解耦了使用自定义配置文件的代码。

运行时更改设置

不建议在运行时更改设置. 比如, 不要在view中这样用:

  1. from django.conf import settings
  3. settings.DEBUG = True  # Don't do this!

应该只在 settings 文件中更改设置。

安全

由于配置文件包含敏感信息, 比如数据库密码, 所以应该限制对配置文件的访问. 比如更改文件权限, 从而只能令你和你的Web服务器能读取配置文件. 这在共享主机的环境中非常重要!

可用的配置项

查看 settings 参考 了解完整的配置项列表。

创建你自己的配置文件

没有什么可以阻止你为你的的 Django 应用创建自己的配置，但请遵循以下原则：

  • 所有配置项名称都应大写。
  • 不要重新设置已存在的配置项。

由于配置文件是序列化的，Django 使用列表，但仅是约定俗成。

不设置 DJANGO_SETTINGS_MODULE 时使用配置

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

在这种情况下，可以手动设定 Django 的配置项。要用到下面这个方法:

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

举例：

  1. from django.conf import settings
  3. settings.configure(DEBUG=True)

通过 configure() 可以设置任何配置项，每个参数对应一个值。参数名称必须大写，而且参数名必须是真实存在。没有在 configure() 中出现的设置项在随后用到时，仍会使用默认值。

如果你并不想使用整个框架，仅仅是其中一小部分时，如上述这般配置 Django 是非常必要的。事实上，我们建议您这样做。

因此，通过 settings.configure() 配置 Django 时，并不会对当前进程的环境变量做任何修改。（可以查看 TIME_ZONE 了解为什么要这么做）。这意味着在上述情况下你仍然完全掌控着当前环境。

定制默认配置项

如果你实在不想使用 django.conf.global_settings，而想自定义配置默认值，你可以在调用 configure() 时使用 default_settings 参数（或是默认做为第一个参数传入）。该参数是一个提供默认值的模块或是类。

在下面这个例子中，由 myapp_defaults 提供默认值，并令 DEBUG 被置为 True 而不是从 myapp_defaults 中获取:

  1. from django.conf import settings
  2. from myapp import myapp_defaults
  4. settings.configure(default_settings=myapp_defaults, DEBUG=True)

接下来例子使用 myapp_defaults 做为一个位置参数，这和上面的效果是等同的:

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

Normally, you will not need to override the defaults in this fashion. The Django defaults are sufficiently tame that you can safely use them. Be aware that if you do pass in a new default module, it entirely replaces the Django defaults, so you must specify a value for every possible setting that might be used in the code you are importing. Check in django.conf.settings.global_settings for the full list.

configure() 或 DJANGO_SETTINGS_MODULE 二者必用其一

如果你没有设置 DJANGO_SETTINGS_MODULE 环境变量，就 必须 在运行读取配置项的代码之前调用 configure()。

如果你没有设置 DJANGO_SETTINGS_MODULE 也没有调用 configure()，那么 Django 会在第一次访问配置项时抛出 ImportError 异常。

如果设置了 DJANGO_SETTINGS_MODULE，以某种方式访问配置的值，再 调用 configure() 的话，Django 将会抛出一个 RuntimeError 异常，表明已经设置了配置。

django.conf.settings.configured

例如：

  1. from django.conf import settings
  3. if not settings.configured:
  4.     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 的应用注册表。例子:

  1. import django
  2. from django.conf import settings
  3. from myapp import myapp_defaults
  5. settings.configure(default_settings=myapp_defaults, DEBUG=True)
  6. django.setup()
  8. # Now this script or any imported module can use any part of Django it needs.
  9. from myapp import models

注意，仅在你的代码是真的独立的情况下调用 django.setup()。当被你的 Web 服务器调用时，或通过 django-admin 调用，Django 会帮你处理这些。

django.setup() 只需调用一次。

因此，避免将可服用的应用逻辑代码放入独立脚本中。是故，你必须在你的应用中从此脚本中导入。若你无法避免这样做，将 django.setup() 调用至于 if 块内:

  1. if __name__ == "__main__":
  2.     import django
  4.     django.setup()

参见

配置参考

包含对于 core 和 contrib 的完整应用配置列表。