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

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

## 基础

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

一组配置例子:

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

> **Note**
>
> 如果你将 [`DEBUG`](/zh-hans/6.0/ref/settings/#std-setting-DEBUG) 设置为 `False`，同时你需要正确的设置 [`ALLOWED_HOSTS`](/zh-hans/6.0/ref/settings/#std-setting-ALLOWED_HOSTS)。

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

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

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

## 指定配置文件

#### `DJANGO_SETTINGS_MODULE`

当你使用 Django 的时候，你必须告诉它你正在使用哪些设置。通过使用环境变量 [`DJANGO_SETTINGS_MODULE`](#envvar-DJANGO_SETTINGS_MODULE) 来实现。

The value of [`DJANGO_SETTINGS_MODULE`](#envvar-DJANGO_SETTINGS_MODULE) should be in Python path syntax,
e.g. `mysite.settings`. Note that the settings module should be on the
Python [`sys.path`](https://docs.python.org/3/library/sys.html#sys.path).

### `django-admin` 工具

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

示例（Unix Bash shell）：

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

示例（Windows shell）：

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

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

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

### 服务器端 (`mode_wsgi`)

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

```
import os

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

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

## 默认配置

Django 的设置文件如果不需要的话，不必定义任何设置。每个设置都有一个合理的默认值。这些默认值存储在模块 [django/conf/global\_settings.py](https://github.com/django/django/blob/stable/6.0.x/django/conf/global_settings.py) 中。

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

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

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

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

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

想了解更多, 可以查看 [`diffsettings`](/zh-hans/6.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 参考](/zh-hans/6.0/ref/settings/) 了解完整的配置项列表。

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

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

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

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

## 不设置 [`DJANGO_SETTINGS_MODULE`](#envvar-DJANGO_SETTINGS_MODULE) 时使用配置

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

在这种情况下，可以手动设定 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/6.0/ref/settings/#std-setting-TIME_ZONE) 了解为什么要这么做）。这意味着在上述情况下你仍然完全掌控着当前环境。

### 定制默认配置项

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

在下面这个例子中，由 `myapp_defaults` 提供默认值，并令 [`DEBUG`](/zh-hans/6.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` 中查看完整的列表。

### `configure()` 或 [`DJANGO_SETTINGS_MODULE`](#envvar-DJANGO_SETTINGS_MODULE) 二者必用其一

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

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

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

#### `django.conf.settings.configured`

例如：

```
from django.conf import settings

if not settings.configured:
    settings.configure(myapp_defaults, DEBUG=True)
```

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

这意味着：确保要使用 `configure()` 或 [`DJANGO_SETTINGS_MODULE`](#envvar-DJANGO_SETTINGS_MODULE) 其中一个，不要多，也不要少。

### “独立的” Django 应用要求调用 `django.setup()`

如果你使用了“独立” Django 的组件——比如，编写一个 Python 脚本，它加载了一些 Django 模板并渲染了它们，或使用 ORM 获取数据——你需要额外的配置一下设置文件。

After you've either set [`DJANGO_SETTINGS_MODULE`](#envvar-DJANGO_SETTINGS_MODULE) or called
`configure()`, you'll need to call [`django.setup()`](/zh-hans/6.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
```

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

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

> **See also**
>
> **[配置参考](/zh-hans/6.0/ref/settings/)**
>
>   包含对于 core 和 contrib 的完整应用配置列表。