---
title: "Django settings"
version: 2.0
locale: zh-hans
source: https://docs.djangoproject.com/zh-hans/2.0/topics/settings/
canonical: https://djangodocs.dev/zh-hans/2.0/topics/settings/
---
# Django settings

Django的settings文件包含Django应用的所有配置项。该文档会介绍settings是如何运行，以及有哪些设置项是可用的。

## 基础

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

一组配置例子:

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

> **Note**
>
> If you set [`DEBUG`](/zh-hans/2.0/ref/settings/#std-setting-DEBUG) to `False`, you also need to properly set
> the [`ALLOWED_HOSTS`](/zh-hans/2.0/ref/settings/#std-setting-ALLOWED_HOSTS) setting.

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

- 不能有Python语法错误
- 可以用Python语法实现动态配置，例如:

  ```
  MY_SETTING = [str(i) for i in range(30)]
  ```
- 可以从其他配置文件中引入变量

## 指定配置文件

#### `DJANGO_SETTINGS_MODULE`

使用Django时要通知Django当前使用的是哪个配置文件。可以改变环境变量 `DJANGO_SETTINGS_MODULE` 实现这一点。

`DJANGO_SETTINGS_MODULE` 的值是一个符合Python语法的路径，比如 `mysite.settings` 。要注意settings模块应该在Python可搜索到的路径中 [import search path](http://www.diveintopython3.net/your-first-python-program.html#importsearchpath).

### The `django-admin` utility

When using [django-admin](/zh-hans/2.0/ref/django-admin/), you can either set the
environment variable once, or explicitly pass in the settings module each time
you run the utility.

例子（Unix Bash shell）:

```
export DJANGO_SETTINGS_MODULE=mysite.settings
django-admin runserver
```

例子（Windows shell）:

```
set DJANGO_SETTINGS_MODULE=mysite.settings
django-admin runserver
```

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

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

### On the server (`mod_wsgi`)

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

```
import os

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

阅读 [Django mod\_wsgi documentation](/zh-hans/2.0/howto/deployment/wsgi/modwsgi/) 了解更多关于Django WSGI应用的信息和相关设置。

## 默认配置

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

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

- 从 `global_settings.py` 中加载配置项
- 从指定的配置文件中加载配置项, 覆盖对应的全局配置项.

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

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

查看你修改了哪几个配置项很容易, 在命令行输入 `python manage.py diffsettings` 就会显示当前配置与默认配置中的不同.

想了解更多, 可以查看 [`diffsettings`](/zh-hans/2.0/ref/django-admin/#django-admin-diffsettings) 文档.

## 在Python代码中使用settings

在具体的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` 整合了默认配置和网站指定配置, 从而只提供一个接口读取配置. 它也解耦了使用自定义配置文件的代码.

## 运行时更改设置

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

```
from django.conf import settings

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

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

## 安全

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

## 可用的配置项

查看 [settings reference](/zh-hans/2.0/ref/settings/) 了解完整的配置项列表.

## 创建你自己的配置文件

There's nothing stopping you from creating your own settings, for your own
Django apps. Just follow these guidelines:

- Setting names must be all uppercase.
- 不要重新设置已存在的配置项.

For settings that are sequences, Django itself uses lists, but this is only
a convention.

## Using settings without setting `DJANGO_SETTINGS_MODULE`

某些场合中, 你想绕过 `DJANGO_SETTINGS_MODULE` 环境变量来进行配置. 比如, 你正在使用django自带的模板系统, 而你并不想使用环境变量指定某个具体的配置文件.

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

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

举例：

```
from django.conf import settings

settings.configure(DEBUG=True)
```

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

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

因此, 通过 `settings.configure()` 配置django时, 并不会对当前进程的环境变量做任何修改.（可以查看 [`TIME_ZONE`](/zh-hans/2.0/ref/settings/#std-setting-TIME_ZONE) 了解为什么要这么做）. 这意味着在上述情况下你仍然完全掌控着当前环境.

### 定制默认配置项

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

在下面这个例子中, 由 `myapp_defaults` 提供默认值, 并令 [`DEBUG`](/zh-hans/2.0/ref/settings/#std-setting-DEBUG) 被置为 `True` 而不是从 `myapp_defaults` 中获取:

```
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` 了解全部默认值.

### Either `configure()` or `DJANGO_SETTINGS_MODULE` is required

在没有设置 `DJANGO_SETTINGS_MODULE` 环境的情况下, 就 *必须* 在运行读取配置项的代码之前就调用 `configure()` .

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

如果已经调了 `DJANGO_SETTINGS_MODULE` , 再调用 `configure()` 的话, Django也会抛出一个 `RuntimeError` 异常, 表明已经配置了settings.

例如:

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

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

这意味着: 确保要使用 `configure()` 或 `DJANGO_SETTINGS_MODULE` 其中一个, 不要多, 也不要少.

### Calling `django.setup()` is required for "standalone" Django usage

If you're using components of Django "standalone" -- for example, writing a
Python script which loads some Django templates and renders them, or uses the
ORM to fetch some data -- there's one more step you'll need in addition to
configuring settings.

After you've either set [`DJANGO_SETTINGS_MODULE`](#envvar-DJANGO_SETTINGS_MODULE) or called
`configure()`, you'll need to call [`django.setup()`](/zh-hans/2.0/ref/applications/#django.setup) to load your
settings and populate Django's application registry. For example:

```
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
```

Note that calling `django.setup()` is only necessary if your code is truly
standalone. When invoked by your Web server, or through [django-admin](/zh-hans/2.0/ref/django-admin/), Django will handle this for you.

> **django.setup() may only be called once.**
>
> Therefore, avoid putting reusable application logic in standalone scripts
> so that you have to import from the script elsewhere in your application.
> If you can't avoid that, put the call to `django.setup()` inside an
> `if` block:
>
> ```
> if __name__ == '__main__':
>     import django
>     django.setup()
> ```

> **See also**
>
> **[The Settings Reference](/zh-hans/2.0/ref/settings/)**
>
>   Contains the complete list of core and contrib app settings.