深度解读Django settings.py：从核心配置到高级实战的完整指南

在 Django 项目里，如果只挑一个“最值得反复回看”的文件，settings.py 一定排在最前面。

它不是业务代码，却决定了项目能不能启动、怎么启动、上线安不安全、报错能不能看懂。很多初学者卡 Django，往往不是卡在视图、模型、接口，而是对这个配置文件一知半解。

这一节课，我们就专门把 settings.py 拆开讲清楚。

一、从项目结构说起：settings.py 在哪、管什么

先简单回顾一下 Django 项目的基本结构。

上节课我们创建了第一个 Django 项目 mysite1，用 tree 命令看到的结构大致是：

• manage.py

• mysite1/

• settings.py
• urls.py
• wsgi.py

• db.sqlite3

这里有几个关键点：

• manage.py用来调用 Django 的各种子命令，比如我们已经用过的 runserver。

• 同名项目目录（mysite1）这是项目真正的“控制中心”：

• settings.py：项目的核心配置文件
• urls.py：主路由入口
• wsgi.py：正式环境启动时使用

• db.sqlite3默认数据库文件，用来存数据。后面会换成 MySQL。

这一节课，我们的注意力只放在一个文件上：settings.py。

二、settings.py 是什么？为什么 Django 离不开它

一句话概括：

Django 是一个重度 Web 框架，几乎所有内置能力，都需要通过配置来“打开”或“约束”。

这也是 Django 和 Flask 最大的差异之一。

• Flask： 功能相对轻量，很多东西要你自己写
• Django： 功能已经帮你写好，但是否启用、如何运行，全靠配置

而这些配置，绝大多数都集中在 settings.py 里。

更重要的一点是：

每一个 Django 项目，都有自己独立的一份 settings.py，互不影响。

三、settings.py 里的配置，分哪两类？

从工程视角看，settings.py 里的内容可以分成两大类。

1️⃣ 公有配置（Django 官方配置）

这是 Django 已经帮你定义好的配置项：

• 名字是固定的
• 含义是官方规定的
• 你只能按规则使用或修改

特点是：多、全、但不用一口气学完。

正确姿势是：

• 先记住高频配置项
• 用到高级功能时，再按需查官方文档

2️⃣ 自定义配置（项目自己的配置）

当项目复杂起来之后，你一定会遇到这些情况：

• 一些常量在多处使用
• 一些开关需要集中管理
• 不想把“魔法值”散落在代码里

这时候，就可以把自定义配置项统一放进 settings.py。

四、配置项的基本规范（很容易踩坑）

Django 对配置项有一个非常严格但简单的规范：

配置项必须是大写的全局变量名

例如：

DEBUG = True
ALLOWED_HOSTS = []

如果你写成小写：

debug = True

项目启动时就会直接报错。

另外，配置项的值类型是灵活的：

• 字符串
• 列表
• 字典
• 布尔值

具体用什么类型，取决于 Django 对这个配置项的定义。

五、正确打开项目，比你想象得重要

一个非常“工程味”的细节：

用 PyCharm 打开 Django 项目，一定要打开到“项目真实根目录”。

也就是说：

• 不要从更高层的目录打开
• 不要只打开某一个子文件夹

否则在导包、路径解析时，很容易出现各种“莫名其妙”的问题。

六、第一个高频配置：BASE_DIR 是怎么来的？

在 settings.py 里，你会看到一个看起来很“绕”的配置：

BASE_DIR = Path(__file__).resolve().parent.parent

它的目的只有一个：

计算出“项目的绝对路径”

拆开来看：

• __file__：当前文件本身（settings.py）
• resolve() / abspath：拿到绝对路径
• parent / dirname：一层一层往上找目录

最终得到的，就是整个 Django 项目的根路径。

这个配置后面会高频出现在这些地方：

• 注册静态文件目录
• 加载 CSS / JS
• 指定模板路径
• 配置日志文件位置

理解一次，后面就不容易迷路。

七、DEBUG：开发模式 vs 上线模式

DEBUG 是 Django 里最具“性格差异”的配置。

它只有两个值：

• True：调试模式
• False：上线模式

调试模式（DEBUG=True）

特点非常明显：

• 改代码自动重启
• 报错页面信息量极大
• 直接把调用栈、变量值都展示出来

这也是为什么很多人第一次看到 Django 报错页面会被“吓到”。

但从工程角度看，它其实是一个极强的排错工具。

上线模式（DEBUG=False）

上线后必须关掉 DEBUG：

• 不再展示详细报错
• 只返回简单错误页面
• 避免泄露系统内部信息

一句话总结：

开发时靠 DEBUG 找问题，上线时靠 DEBUG=false 保安全。

八、ALLOWED_HOSTS：你到底在让谁访问你的服务

这是一个经常被忽视、但非常重要的安全配置。

它的作用只有一个：

校验 HTTP 请求头里的 Host 值，只接收“合法来源”的请求。

开发阶段

• 当 DEBUG=True 时

• Django 默认允许：

• 127.0.0.1
• localhost

通常不需要额外配置。

测试 / 局域网访问

如果你希望别的机器访问你的 Django 服务：

1. 启动方式要改成：

python manage.py runserver 0.0.0.0:8000

1. 把内网 IP 加入 ALLOWED_HOSTS

否则即使端口是通的，也访问不到。

正式上线

上线时的原则很明确：

• 不要用 *
• 明确写域名或公网 IP
• 过滤掉“不是访问你这个站点”的请求

这是 Django 提供的一道基础防线。

九、其他常见但暂时不深挖的配置项

在 settings.py 里，你还会看到这些熟面孔：

• INSTALLED_APPS：应用注册
• MIDDLEWARE：中间件链
• TEMPLATES：模板配置
• DATABASES：数据库配置（SQLite → MySQL）
• WSGI_APPLICATION：正式环境启动入口
• ROOT_URLCONF：主路由位置

这些配置都会在后续章节单独展开，这一节只需要知道它们各自负责什么领域即可。

十、语言与时区：别让时间和语言“骗了你”

两个非常容易被忽略、但影响体验的配置：

语言配置

LANGUAGE_CODE = 'zh-hans'

改完之后：

• 管理后台
• Django 默认页面

都会切换为中文。

时区配置

TIME_ZONE = 'Asia/Shanghai'

默认是 UTC（格林威治时间），改成东八区后：

• 日志时间
• 数据时间戳

都会更符合国内使用习惯。

十一、自定义配置：放哪？怎么命名？

结论很简单：

• 可以直接放在 settings.py
• 必须是大写变量名
• 尽量个性化，避免和官方配置重名

例如：

ORDER_EXPIRE_SECONDS = 900

比：

TIMEOUT = 900

安全得多。

十二、代码里怎么正确引用配置？

这是一个非常关键的细节。

正确方式是：

from django.conf import settings

而不是：

import settings

原因在于：

• Django 会对 settings 做一层封装
• 直接 import 文件，容易绕过 Django 的配置体系

无论是公有配置还是自定义配置，都通过这个 settings 来取。

结语：settings.py 是 Django 的“控制面板”

这一节课，其实只做了一件事：

把 settings.py 从“看不懂的配置堆”，变成“有结构、有边界的控制面板”。

你现在至少应该清楚：

• settings.py 分公有配置和自定义配置
• BASE_DIR、DEBUG、ALLOWED_HOSTS 是高频核心
• 语言、时区、数据库不是“顺手改”，而是有工程含义
• 自定义配置要规范、要克制

下一节课开始，我们会逐步把这些配置真正用起来，而不是只停留在“看懂”。

Django 很重，但它的重量，是可以被工程化理解和驾驭的。