在实际的 Web 开发学习路径里Django 往往是继 Python 基础语法之后第一个值得系统投入的 Web 框架。它自带 Admin 后台、ORM、模板系统、表单处理和认证机制非常适合用来构建“真实可用”的 Web 应用。这一篇是四部分系列教程的第一部分目标很明确先把 Python 环境、Django 安装、项目结构、URL 到视图的请求链路全部跑通让你在本地看到一个能正常响应浏览器的 Django 应用。后续三部分再依次深入模型与数据库、模板与表单、以及完整的业务项目实战。这篇笔记不会只贴命令而是会解释每一步为什么这样做、哪些参数可以调整、报错时应该看哪里。读完并亲手操作一遍之后你应该能独立创建一个 Django 项目理解项目和应用的区别并且知道如何继续往下写功能。1. 先从整体理解 Django它解决什么问题为什么适合构建真实 Web 应用很多初学者第一次接触 Django 时第一反应是“它和 Flask 有什么区别”。这里先放下框架对比回到 Web 开发本身。一个真实 Web 应用通常包含这几件事接收 HTTP 请求、路由到对应的处理逻辑、读写数据库、渲染页面或返回 JSON、处理用户登录和权限。如果全部手写工作量非常大而且容易在安全和规范上犯错。Django 的核心思路是“batteries included”也就是把 Web 应用最常见的组成部分全部内置。你不需要花大量时间挑选第三方库来拼装一个项目Django 本身提供的组件已经覆盖了绝大多数业务场景。1.1 Django 的核心组成Django 的核心模块可以按职责划分为几块模块作用对应学习重点URL 路由将浏览器请求的路径映射到视图函数或类urls.py、path/re_path视图层处理请求、执行业务逻辑、返回响应FBV 和 CBVORM用 Python 对象操作数据库表models.Model、QuerySet模板系统在 HTML 中渲染动态数据Django Template Language表单处理用户输入、校验、错误提示forms.Form、ModelFormAdmin 后台自动生成数据管理页面django.contrib.admin认证系统用户注册、登录、会话、权限django.contrib.auth中间件在请求和响应之间插入处理逻辑Middleware这个表格不需要现在全部背下来但建议把它当作后续学习的地图。第一部分只需要关注前三行URL、视图、以及如何让项目跑起来。1.2 Django 的请求处理流程理解一个请求从浏览器到服务器的完整路径对排查问题至关重要。一个典型请求的处理顺序是浏览器向服务器发送 HTTP 请求例如访问http://127.0.0.1:8000/index/。Django 按settings.py中ROOT_URLCONF指定的 urls 模块查找匹配的路由。匹配到path(index/, ...)后调用对应的视图函数。视图函数执行业务逻辑可能查询数据库、调用其他函数。视图返回HttpResponse或渲染后的模板。中间件和后端处理响应最终返回给浏览器。这条链路看起来简单但它决定了你以后排查问题时的顺序先看 URL 是否匹配再看视图有没有被执行然后看响应内容是什么最后才怀疑中间件或服务器配置。1.3 Django 适合什么场景不适合什么场景Django 适合内容管理类系统、数据分析展示平台、企业内部系统、电商后台、社区论坛这类需要“用户 数据 后台管理”的项目。它的优势是开发效率高规范和内置功能完善。如果只是一个非常轻量的 API或者只有十几个路由的微型站点Django 会显得重。这时候 Flask 或 FastAPI 更合适。但这个判断要放在实际项目中做初学阶段先把 Django 的完整开发流程走一遍比反复纠结选型更有价值。2. 环境准备Python 版本、虚拟环境和 Django 安装Django 是一个 Python 第三方包所以环境准备的核心是 Python 本身。很多新手在这一步就出现“明明装了 Python却提示找不到命令”的情况大部分原因是安装时没有把 Python 加入 PATH或者终端没有重启。2.1 确认 Python 环境打开终端执行以下命令python --version如果提示找不到命令再试python3 --version在 Windows 上还可能遇到py启动器py --versionDjango 5.x 要求 Python 3.10 及以上版本。如果你的版本低于这个要求建议先从官网下载新版本安装而不是继续在老版本上凑合。版本过低会导致 Django 安装失败或运行时报语法错误。确认 Python 可用之后再确认 pippython -m pip --version这里推荐使用python -m pip而不是直接pip因为前者能确保 pip 与当前 Python 解释器对应避免多版本环境下安装到错误位置。2.2 创建虚拟环境虚拟环境的作用是隔离项目依赖。不同项目依赖的 Django 版本可能不同如果不隔离升级一个项目依赖时可能影响另一个项目。创建虚拟环境的命令# 在项目根目录执行 python -m venv venvWindows 激活方式venv\Scripts\activatemacOS / Linux 激活方式source venv/bin/activate激活成功后终端提示符前面会出现(venv)字样。此时执行的python和pip都指向虚拟环境不会污染系统全局环境。不需要隔离环境时退出命令是deactivate2.3 安装 Django 并确认版本激活虚拟环境后安装 Djangopip install django如果想安装指定版本例如 5.0 LTS 系列pip install django5.0.*安装完成后确认版本python -m django --version这里的django-admin是 Django 提供的命令行工具后面创建项目会用到。2.4 环境检查清单每次开始一个新项目前建议按以下顺序确认环境检查项命令预期结果Python 版本python --version3.10 及以上pip 可用python -m pip --version显示 pip 版本号虚拟环境激活which python或where python路径指向项目内 venvDjango 已安装python -m django --version显示版本号注意如果django-admin命令找不到优先改用python -m django。前者依赖 PATH 配置后者由 Python 解释器直接调用更不容易出错。3. 创建第一个 Django 项目项目与应用的职责拆分环境准备完成后进入最核心的创建环节。这里要先理解一个容易混淆的概念Django 项目中“项目”和“应用”是两个不同层次的东西。项目是一个完整的网站或服务它负责整体配置、URL 入口、数据库设置。应用是项目中的一个功能模块例如一个博客系统可以有articles应用、comments应用、users应用。项目可以包含多个应用应用也可以被多个项目复用。3.1 创建项目在终端中进入你希望存放代码的目录执行django-admin startproject myproject如果刚才的django-admin不可用使用python -m django startproject myproject执行后会在当前目录生成一个myproject文件夹。进入这个文件夹并启动开发服务器验证基本环境是否正常cd myproject python manage.py runserver浏览器访问http://127.0.0.1:8000/看到 Django 的默认欢迎页面说明环境已经跑通。3.2 理解项目目录结构创建后的目录结构如下myproject/ ├── manage.py └── myproject/ ├── __init__.py ├── asgi.py ├── settings.py ├── urls.py └── wsgi.py每个文件的职责文件作用manage.py项目管理入口运行开发服务器、执行迁移、创建应用都靠它settings.py全局配置包括数据库、应用注册、模板、静态文件urls.py项目的 URL 总入口wsgi.py/asgi.py部署时给服务器使用的接口__init__.py标识目录是一个 Python 包新手最容易犯的错误是直接改外层myproject目录里的文件或者在错误的层级执行manage.py。记住manage.py在哪一层就在哪一层执行命令。3.3 创建应用项目创建好之后创建第一个应用。这里以blog为例python manage.py startapp blog执行后目录中多出blog/文件夹里面有views.py、models.py、admin.py、migrations/等文件。这些文件就是后续开发的主要战场。3.4 注册应用创建完应用后必须告诉 Django“这个应用属于当前项目”。在settings.py中找到INSTALLED_APPS把blog加进去INSTALLED_APPS [ django.contrib.admin, django.contrib.auth, django.contrib.contenttypes, django.contrib.sessions, django.contrib.messages, django.contrib.staticfiles, blog, # 新增这一行 ]不注册应用Django 不会为它执行数据库迁移也不会加载它的模板和静态文件。这是新手经常会漏掉的一步。4. 编写第一个视图从 urls 到 views 的完整请求链路视图是 Django 处理请求的核心。这一节用一个最简单的“首页”视图把 URL 配置、视图函数和浏览器访问串起来。4.1 编写视图函数打开blog/views.py写入from django.http import HttpResponse def index(request): return HttpResponse(欢迎来到我的第一个 Django 页面)这个视图只有一个参数request它封装了浏览器发来的所有请求信息。函数返回一个HttpResponseDjango 会把这个响应内容发送回浏览器。4.2 配置 URLDjango 的路由配置分为两层。项目总路由在myproject/urls.py中应用自己的路由通常在应用目录下新建urls.py。先修改项目总路由myproject/urls.pyfrom django.contrib import admin from django.urls import path, include urlpatterns [ path(admin/, admin.site.urls), path(, include(blog.urls)), ]然后在blog目录下新建urls.pyfrom django.urls import path from . import views urlpatterns [ path(, views.index, nameindex), ]path(, views.index, nameindex)表示访问根路径/时调用views.index。name参数是路由的别名后面在模板中用{% url %}反向解析 URL 时会用到。4.3 启动开发服务器回到项目根目录运行python manage.py runserver默认监听127.0.0.1:8000。如果想换端口python manage.py runserver 8080开发服务器支持代码修改后自动重载不需要手动重启。但新增文件、迁移数据库、修改settings.py中部分参数时有时需要手动重启才能生效。4.4 验证结果浏览器访问http://127.0.0.1:8000/页面应该显示欢迎来到我的第一个 Django 页面此时可以验证一下 URL 配置的效果。把blog/urls.py改成urlpatterns [ path(hello/, views.index, nameindex), ]访问http://127.0.0.1:8000/hello/才能看到内容访问根路径会变成 404。这说明路由匹配是精确的字符串必须一致。注意Django 对 URL 末尾的斜杠有重定向机制。访问/hello时如果配置写的是/hello/Django 默认会返回 301 重定向到/hello/。这个行为由APPEND_SLASH控制默认开启。5. 理解关键的配置项settings.py 中必须认识的参数到了这一步项目已经能跑通完整请求链路。接下来需要理解settings.py中最常用的几个配置项因为后面所有功能开发都会和它们打交道。5.1 常用配置参数速查参数默认值作用DEBUGTrue是否开启调试模式生产环境必须为 FalseALLOWED_HOSTS[]允许访问的主机名列表INSTALLED_APPS内置应用列表注册项目中的所有应用DATABASESsqlite3数据库连接配置LANGUAGE_CODEen-us默认语言TIME_ZONEUTC时区USE_TZTrue是否启用时区支持STATIC_URL/static/静态文件 URL 前缀ROOT_URLCONF项目名.urls总路由位置5.2 DEBUG 模式DEBUG True时Django 会在页面显示详细报错信息包括异常堆栈、模板错误、SQL 语句等。这对开发排查很有帮助但生产环境开启会有严重安全风险会暴露文件路径、配置信息和数据库结构。修改为 False 后必须同步配置ALLOWED_HOSTS例如DEBUG False ALLOWED_HOSTS [example.com, www.example.com]否则访问时会提示DisallowedHost错误。5.3 数据库配置默认使用 SQLite配置如下DATABASES { default: { ENGINE: django.db.backends.sqlite3, NAME: BASE_DIR / db.sqlite3, } }SQLite 的特点是零配置、单文件适合学习和中小型项目。切换到 MySQL 或 PostgreSQL 时需要修改ENGINE和连接参数同时安装对应的数据库驱动。学习阶段不必急着换数据库先把 SQLite 用明白。5.4 静态文件和模板静态文件是 CSS、JavaScript、图片这类不需要服务端处理的资源。Django 开发环境下只要配置了STATIC_URL在模板中就可以通过{% load static %}和{% static css/style.css %}引用。模板路径默认按应用目录查找每个应用下的templates文件夹会被 Django 自动识别。多个应用有同名模板时建议在模板文件夹内再加一层以应用名命名的子目录例如blog/templates/blog/index.html避免模板冲突。6. 常见问题排查把第一道坎拆开来看新手在完成上述流程时几乎一定会遇到下面几类问题。这里把现象、原因和解决方案整理成一条可直接对照的排查链。6.1 命令找不到或运行的不是预期版本现象执行django-admin提示命令不存在或者pip install django后仍然报错No module named django。排查顺序确认当前是否激活了虚拟环境输入which python看路径。如果路径指向系统 Python说明虚拟环境没有激活或激活失效。改用python -m django --version验证 Django 是否安装到了当前解释器。确认是否安装到了全局环境而不是虚拟环境可以使用pip list查看。解决方案激活正确的虚拟环境后重新安装依赖。不要同时使用pip和pip3混装。6.2 端口被占用现象运行runserver时提示Error: That port is already in use.原因上一个开发服务器没有正确退出或端口被其他程序占用。排查方式# Windows netstat -ano | findstr 8000 # macOS / Linux lsof -i :8000解决方案结束占用进程或者换端口启动python manage.py runserver 80016.3 迁移相关报错现象启动后页面提示You have unapplied migrations。原因Django 内置应用如 admin、auth的数据表还没有创建。解决方案python manage.py migrate这里解释一下migrate的作用Django 用模型描述数据表结构迁移文件记录每一次结构变化migrate命令把这些变化同步到数据库。这也是后续定义模型后必须执行的操作。6.4 模板路径或静态文件找不到现象页面能访问但样式丢失或模板加载报错。排查顺序确认应用是否注册到INSTALLED_APPS。确认模板文件是否在应用目录下的templates文件夹中。确认模板中使用的是{% extends %}和{% block %}是否和母版一致。确认浏览器控制台的 404 路径是否正确必要时清缓存或强制刷新。7. 学习环境与生产环境的差异如何避免“本地能跑部署就崩”很多人在本地开发很顺利一放到服务器上就遇到一系列问题。这不是运气问题而是开发环境与生产环境的设计目标不同。开发环境追求快速迭代和错误可见生产环境追求稳定、安全和性能。7.1 开发服务器和生产服务器的区别runserver是 Django 自带的轻量开发服务器它的文档明确说明不适合生产环境。原因有三个第一并发能力有限。开发服务器是单进程模型无法处理大量并发请求。第二静态文件处理效率低。开发模式下静态文件由 Django 直接返回生产环境应该交给 Nginx 或 CDN。第三安全性不足。开发服务器没有经过完整的加固和性能调优。生产环境通常的做法是使用 Gunicorn 或 uWSGI 作为 WSGI 服务器前面再放 Nginx 处理静态文件和反向代理。7.2 上线前必须检查的配置项配置项开发环境生产环境DEBUGTrueFalseALLOWED_HOSTS留空或 localhost填写实际域名SECRET_KEY默认值必须改为随机长字符串且配置外置数据库SQLite建议 MySQL/PostgreSQL静态文件Django 处理Nginx/CloudFront日志终端输出文件或日志服务SECRET_KEY是签名会话、验证码、CSRF 等安全功能的基础生产环境中不能写死在代码库里。建议使用环境变量读取例如import os SECRET_KEY os.environ.get(DJANGO_SECRET_KEY, dev-only-unsafe-key)这段代码的意思是优先从环境变量DJANGO_SECRET_KEY中读取没有设置时使用默认值。这样既保证本地能跑又避免生产环境使用固定密钥。8. 最佳实践与常见坑从第一步就养成正确的工程习惯这一节把第一部分中最重要的习惯和踩坑经验集中列出。有些问题虽然现在不严重但等代码量变大后再改会非常痛苦。8.1 项目结构建议对于功能逐渐变多的项目推荐的目录组织方式是myproject/ ├── manage.py ├── myproject/ │ ├── settings/ │ │ ├── base.py │ │ ├── dev.py │ │ └── prod.py │ ├── urls.py │ └── wsgi.py ├── apps/ │ ├── blog/ │ └── users/ ├── static/ ├── media/ ├── templates/ └── requirements.txt把settings.py拆分成base.py、dev.py、prod.py可以让不同环境使用不同配置。应用统一放在apps目录下便于管理。这个结构不需要在一开始就完全照搬但建议随着项目增长逐步调整。8.2 至少要注意的三个常见坑第一个坑是“用python还是python3”混淆。在多版本 Python 环境中python可能指向 Python 2 或旧版本导致依赖安装后运行报错。统一在项目内使用虚拟环境并且始终用python -m pip和python -m django可以避免绝大多数版本混乱问题。第二个坑是“修改了代码但页面没有变化”。首先确认开发服务器是否自动重载其次确认是不是浏览器缓存。如果修改的是settings.py或新增了文件手动重启开发服务器往往能解决。第三个坑是“把密钥和敏感配置写进了代码”。日志被推送、代码被公开后SECRET_KEY和数据库密码等于直接泄露。从第一天起就用环境变量管理敏感配置比项目上线前再补救要省事得多。8.3 再看一遍环境检查清单每次新建项目时建议按这个清单快速自检python --version确认 Python 版本满足要求。python -m venv venv创建虚拟环境并激活。pip install django安装依赖。python -m django --version确认 Django 版本。django-admin startproject myproject创建项目。python manage.py startapp blog创建应用。python manage.py migrate初始化数据表。python manage.py runserver启动服务器。浏览器访问根路径确认页面正常。这套流程跑通之后第二部分可以开始引入模型Model和数据库迁移。到那时Django 的 ORM 会成为你操作数据的主要工具而第一部分建立的环境和项目结构会一直伴随着后续开发。建议在继续之前亲手把本文的示例代码从零写一遍越熟练越好。