Django入门指南：从环境搭建到URL与视图的完整请求链路-育师

在实际的 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 和 CBV
ORM	用 Python 对象操作数据库表	models.Model、QuerySet
模板系统	在 HTML 中渲染动态数据	Django Template Language
表单	处理用户输入、校验、错误提示	forms.Form、ModelForm
Admin 后台	自动生成数据管理页面	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 --version

Django 5.x 要求 Python 3.10 及以上版本。如果你的版本低于这个要求，建议先从官网下载新版本安装，而不是继续在老版本上凑合。版本过低会导致 Django 安装失败或运行时报语法错误。

确认 Python 可用之后，再确认 pip：

python -m pip --version

这里推荐使用python -m pip而不是直接pip，因为前者能确保 pip 与当前 Python 解释器对应，避免多版本环境下安装到错误位置。

2.2 创建虚拟环境

虚拟环境的作用是隔离项目依赖。不同项目依赖的 Django 版本可能不同，如果不隔离，升级一个项目依赖时可能影响另一个项目。创建虚拟环境的命令：

# 在项目根目录执行 python -m venv venv

Windows 激活方式：

venv\Scripts\activate

macOS / Linux 激活方式：

source venv/bin/activate

激活成功后，终端提示符前面会出现(venv)字样。此时执行的python和pip都指向虚拟环境，不会污染系统全局环境。

不需要隔离环境时，退出命令是：

deactivate

2.3 安装 Django 并确认版本

激活虚拟环境后安装 Django：

pip install django

如果想安装指定版本，例如 5.0 LTS 系列：

pip install django==5.0.*

安装完成后确认版本：

python -m django --version

这里的django-admin是 Django 提供的命令行工具，后面创建项目会用到。

2.4 环境检查清单

每次开始一个新项目前，建议按以下顺序确认环境：

检查项	命令	预期结果
Python 版本	`python --version`	3.10 及以上
pip 可用	`python -m pip --version`	显示 pip 版本号
虚拟环境激活	`which python`或`where python`	路径指向项目内 venv
Django 已安装	`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，它封装了浏览器发来的所有请求信息。函数返回一个HttpResponse，Django 会把这个响应内容发送回浏览器。

4.2 配置 URL

Django 的路由配置分为两层。项目总路由在myproject/urls.py中，应用自己的路由通常在应用目录下新建urls.py。

先修改项目总路由myproject/urls.py：

from django.contrib import admin from django.urls import path, include urlpatterns = [ path('admin/', admin.site.urls), path('', include('blog.urls')), ]

然后在blog目录下新建urls.py：

from django.urls import path from . import views urlpatterns = [ path('', views.index, name='index'), ]

path('', views.index, name='index')表示访问根路径/时调用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, name='index'), ]

访问http://127.0.0.1:8000/hello/才能看到内容，访问根路径会变成 404。这说明路由匹配是精确的，字符串必须一致。

注意：Django 对 URL 末尾的斜杠有重定向机制。访问/hello时，如果配置写的是/hello/，Django 默认会返回 301 重定向到/hello/。这个行为由APPEND_SLASH控制，默认开启。

5. 理解关键的配置项：settings.py 中必须认识的参数

到了这一步，项目已经能跑通完整请求链路。接下来需要理解settings.py中最常用的几个配置项，因为后面所有功能开发都会和它们打交道。

5.1 常用配置参数速查

参数	默认值	作用
`DEBUG`	True	是否开启调试模式，生产环境必须为 False
`ALLOWED_HOSTS`	[]	允许访问的主机名列表
`INSTALLED_APPS`	内置应用列表	注册项目中的所有应用
`DATABASES`	sqlite3	数据库连接配置
`LANGUAGE_CODE`	en-us	默认语言
`TIME_ZONE`	UTC	时区
`USE_TZ`	True	是否启用时区支持
`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 8001

6.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 上线前必须检查的配置项

配置项	开发环境	生产环境
`DEBUG`	True	False
`ALLOWED_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 会成为你操作数据的主要工具，而第一部分建立的环境和项目结构会一直伴随着后续开发。建议在继续之前，亲手把本文的示例代码从零写一遍，越熟练越好。