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

When you use Django, you have to tell it which settings you’re using. Do this by using an environment variable, DJANGO_SETTINGS_MODULE.

The value of DJANGO_SETTINGS_MODULE should be in Python path syntax, e.g. mysite.settings. Note that the settings module should be on the Python import search path.

django-admin 工具

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

例子（Unix Bash shell）:

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

例子（Windows shell）:

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

使用 --settings 命令行参数指定配置模块路径:

  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 应用的信息和常见设置。

默认配置

在无需配置的情况下，Django配置文件没必要定义任何配置项。因为每个配置项都有一个明确的默认值。默认值都保存在模块 django/conf/global_settings.py 中。

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

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

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

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

The command python manage.py diffsettings displays differences between the current settings file and Django’s default settings.

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

在 Python 代码中使用 settings

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

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

注意 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 参考 了解完整的配置项列表。

创建你自己的配置文件

There’s nothing stopping you from creating your own settings, for your own Django apps, but follow these guidelines:

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

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

Using settings without setting DJANGO_SETTINGS_MODULE

In some cases, you might want to bypass the DJANGO_SETTINGS_MODULE environment variable. For example, if you’re using the template system by itself, you likely don’t want to have to set up an environment variable pointing to a 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)

一般来说，没必要自行设置默认值。Django 的默认设置是比较宽松的，你可以放心地使用。要注意的是，如果你传入了新的默认模块，那它就会完全 替换 Django 本身的默认设置。因此，你必须为接下来可能会用到的所有设置项都重新指定默认值。查看 django.conf.settings.global_settings 了解全部默认值。

Either configure() or DJANGO_SETTINGS_MODULE is required

If you’re not setting the DJANGO_SETTINGS_MODULE environment variable, you must call configure() at some point before using any code that reads settings.

If you don’t set DJANGO_SETTINGS_MODULE and don’t call configure(), Django will raise an ImportError exception the first time a setting is accessed.

If you set DJANGO_SETTINGS_MODULE, access settings values somehow, then call configure(), Django will raise a RuntimeError indicating that settings have already been configured. There is a property for this purpose:

例如:

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

重复调用 configure() 或是在访问任何一个配置项后再调用 configure()，也会引起错误。

It boils down to this: Use exactly one of either configure() or DJANGO_SETTINGS_MODULE. Not both, and not neither.

“独立的” 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
  3.     django.setup()

参见

配置参考

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