Django项目中，settings、urls、wsgi文件分别扮演什么角色？

本文共计1216个文字，预计阅读时间需要5分钟。

很多人以为修改了 `settings.py` 就能立即生效，实际上它只是被其他模块导入读取的配置容器。Django 启动时不会直接执行它，而是通过 `Django.setup()` 或命令行工具（如 `manage.py runserver`）按需加载。

常见错误现象：ImportError: No module named 'myapp'，往往是因为 INSTALLED_APPS 里写了错路径，或没把 app 所在目录加进 PYTHONPATH；DEBUG = False 后静态文件 404，其实是没配 STATIC_ROOT 和没运行 python manage.py collectstatic。

• SECRET_KEY 必须在生产环境换掉，不能用默认值或硬编码在代码里
• DATABASES 的 ENGINE 值要写全，比如 'django.db.backends.postgresql'，少个 postgresql 就报 django.core.exceptions.ImproperlyConfigured
• 环境差异建议拆成 settings/base.py + settings/production.py，用 python manage.py runserver --settings=myproject.settings.production 指定

urls.py 控制请求分发，不是路由定义本身

urls.py 的本质是 URL 模式匹配表，它不处理业务逻辑，只决定“这个请求交给哪个视图”。主 urls.py（通常在项目根目录）负责一级分发，各 app 自己的 urls.py 负责二级细化。

常见错误现象：访问 /admin/ 报 404，大概率是主 urls.py 里漏了 path('admin/', admin.site.urls)；访问 /api/users/ 报 NoReverseMatch，常因 include() 时没传 namespace 或视图函数名拼错。

• 用 include() 引入 app 的 urls.py 时，推荐加 namespace 参数，比如 include('users.urls', namespace='users')，避免反向解析冲突
• path() 和 re_path() 不兼容参数：前者用 <pk></pk>，后者得写正则 (?P<pk>\d+)</pk>，混用会报 TypeError: path() got an unexpected keyword argument 'name'
• 调试时可临时在主 urls.py 加 print("URLs loaded")，确认它真被导入了（有时因 import 循环根本没执行）

wsgi.py 是 Web 服务器和 Django 的胶水层

wsgi.py 文件只在部署时起作用，本地 runserver 用的是 Django 自带的 WSGIHandler，不走这个文件。它本质是一个符合 WSGI 协议的 Python 可调用对象（application），供 Gunicorn、uWSGI 等调用。

常见错误现象：Gunicorn 启动报 ModuleNotFoundError: No module named 'myproject'，是因为 cd 到错目录或 --chdir 没设对；Nginx 返回 502，常因 wsgi.py 里 os.environ.setdefault('DJANGO_SETTINGS_MODULE', 'myproject.settings') 的路径写错了。

• os.environ.setdefault() 必须在 django.core.wsgi.get_wsgi_application() 之前调用，顺序颠倒会触发 ImproperlyConfigured
• 生产环境别在 wsgi.py 里写业务逻辑，比如数据库连接或缓存初始化——这些该放 ready() 信号或单独初始化模块里
• 如果用多 settings（如 staging/production），wsgi.py 中的 DJANGO_SETTINGS_MODULE 值必须和实际部署环境一致，不能依赖开发机上的 shell 环境变量

项目根目录下 manage.py 不是必须的，但删了就得手动补

manage.py 就是个带了 os.environ.setdefault('DJANGO_SETTINGS_MODULE', ...) 的脚本封装，它让命令行工具（runserver、migrate）知道该用哪套配置。没有它也能用 django-admin，但得每次都传 --settings。

容易被忽略的点：有些团队把 manage.py 改名或挪走，结果 CI 流水线跑 python manage.py test 直接失败；或者在 Dockerfile 里 COPY 错了路径，导致容器内找不到 manage.py。

• manage.py 开头的 #!/usr/bin/env python 在 Windows 上无效，但没关系——Windows 用户本来就不靠 shebang 启动
• 如果项目结构是 src/myproject/，那 manage.py 必须放在跟 src 同级，并在 sys.path 插入 src 目录，否则 import myproject 会失败
• manage.py 里的 if __name__ == '__main__': 块不能删，这是命令行入口的守门人

最麻烦的其实是路径和环境变量的耦合：settings.py 里写的 BASE_DIR / 'static'、wsgi.py 里依赖的 DJANGO_SETTINGS_MODULE、manage.py 里设定的 sys.path——三者稍有不一致，服务就起不来，而且错误提示往往不直接指向根源。