Django入门教程（二十）：博客项目实战（一）——环境搭建与第一个Django页面

一、项目概述

本章开始，我们将从零创建一个完整的博客项目，把前面学到的知识串联起来。在这个过程中，你会真正理解 Django 的项目结构和请求生命周期。

本篇目标：

搭建独立的虚拟环境
创建 Django 项目与博客应用
理解 Django 请求生命周期
完成第一个页面（URL → View → Template）

二、环境准备

1. 检查 Python 版本

Django 是 Python Web 框架，需要先确认 Python 环境。打开终端：

bash
复制代码
$ python3 --version
Python 3.12.0

要求： Python 3.8 以上版本。

2. 创建虚拟环境

虚拟环境是 Python 项目的标准实践，让每个项目有独立的依赖，互不干扰。

bash

复制代码

$ python3 -m venv venv               # 创建虚拟环境
$ source venv/bin/activate           # 激活虚拟环境
# Windows 使用：venv\Scripts\activate
(venv) $ pip install django          # 在虚拟环境中安装 Django

验证安装：

bash

复制代码

(venv) $ python -m django --version
5.0

重要提醒： 每次打开新终端，都需要先执行 source venv/bin/activate 激活虚拟环境。终端提示符前面的 (venv) 表示当前已在虚拟环境中。

三、创建 Django 项目

Django 提供了 django-admin startproject 命令来初始化项目：

bash

复制代码

(venv) $ django-admin startproject blog_project
(venv) $ cd blog_project

生成的目录结构：

text

复制代码

blog_project/
├── manage.py                    # 项目管理入口
├── blog_project/                # 项目配置包
│   ├── __init__.py              # 标识这是一个 Python 包
│   ├── settings.py              # 全局配置
│   ├── urls.py                  # 根 URL 路由表
│   ├── wsgi.py                  # WSGI 部署入口（生产环境用）
│   └── asgi.py                  # ASGI 部署入口（WebSocket 用）

各文件职责：

文件	作用
`manage.py`	启动服务器、执行迁移、创建 admin 等
`settings.py`	数据库、中间件、模板、静态文件等全局配置
`urls.py`	根 URL 路由表
`wsgi.py`	传统同步部署入口
`asgi.py`	异步部署入口

四、启动开发服务器

bash

复制代码

(venv) $ python manage.py runserver
Watching for file changes with StatReloader
Performing system checks...
System check identified no issues (0 silenced).
Starting development server at http://127.0.0.1:8000/

浏览器访问 http://127.0.0.1:8000/，看到 Django 的欢迎页面（火箭图标），说明启动成功。

提示： 开发服务器自带热重载：修改代码保存后，服务器会自动重启。按 Ctrl+C 停止服务器。

五、settings.py 关键配置

settings.py 是 Django 项目的中央配置文件。以下是几个最常用的配置项：

配置项	默认值	作用
`DEBUG`	`True`	开发模式（上线后必须设为 `False`）
`DATABASES`	SQLite	数据库配置（默认 SQLite，无需额外安装）
`INSTALLED_APPS`	内置应用列表	注册到项目的应用
`TEMPLATES`	DjangoTemplates	模板引擎配置
`LANGUAGE_CODE`	`'en-us'`	语言
`TIME_ZONE`	`'UTC'`	时区

改为中文环境：

python

复制代码

# 文件路径：blog_project/settings.py
LANGUAGE_CODE = 'zh-hans'      # 后台管理界面显示中文
TIME_ZONE = 'Asia/Shanghai'    # 时区设置为北京时间

六、创建第一个应用：blog

Django 的项目组织方式是项目（Project）包含多个应用（App）。每个 App 负责一个独立的功能模块（如博客、用户、评论）。

bash

复制代码

(venv) $ python manage.py startapp blog

生成的 blog/ 目录：

text

复制代码

blog/
├── __init__.py
├── admin.py       # 后台管理配置
├── apps.py        # 应用配置
├── models.py      # 数据库模型
├── views.py       # 视图函数
├── urls.py        # 需要手动创建（应用级路由）
└── migrations/    # 数据库迁移文件

注册应用： 创建 App 后，必须在 settings.py 中注册，Django 才能识别它。

python

复制代码

# 文件路径：blog_project/settings.py
INSTALLED_APPS = [
    'django.contrib.admin',
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'django.contrib.messages',
    'django.contrib.staticfiles',
    'blog',                      # 新增：注册 blog 应用
]

七、Django 请求生命周期

理解请求在 Django 中的流转过程，有助于后续快速定位问题。

核心流程：

text

复制代码

浏览器输入 URL → urls.py 匹配路由 → views.py 处理逻辑 → templates 渲染 HTML → 返回浏览器

三步走开发模式：

步骤	文件	职责
URL	`urls.py`	将 URL 映射到视图
View	`views.py`	处理业务逻辑，准备数据
Template	`templates/*.html`	渲染 HTML 页面

这三步是 Django 开发的骨架模式，后续所有功能都会围绕它展开。

八、动手：第一个 Django 页面

第一步：编写视图函数

python

复制代码

# 文件路径：blog/views.py
from django.shortcuts import render

# 视图函数：接收 request，返回 response
def index(request):
    # render 的作用：组合 request + 模板 + 数据，返回 HTML 响应
    return render(request, 'blog/index.html', {
        'welcome': '欢迎来到 RUNOOB 博客',
        'intro': '这是一个用 Django 构建的个人博客展示站。'
    })

render 的三个参数：

request：请求对象（必须）
'blog/index.html'：模板路径
{...}：传递给模板的上下文字典

第二步：创建模板文件

在 blog/ 目录下创建 templates/blog/ 子目录，然后创建 index.html：

html

复制代码

<!-- 文件路径：blog/templates/blog/index.html -->
<!DOCTYPE html>
<html lang="zh-CN">
<head>
    <meta charset="UTF-8">
    <title>RUNOOB 博客</title>
    <style>
        body { font-family: sans-serif; max-width: 800px; margin: 0 auto; padding: 40px 20px; }
        h1 { color: #2c3e50; }
    </style>
</head>
<body>
    <h1>{{ welcome }}</h1>
    <p>{{ intro }}</p>
</body>
</html>

要点： Django 模板变量使用 {``{ 变量名 }} 语法。views.py 中传给 render 的字典数据，在模板中可以直接用。

模板目录结构说明：

text

复制代码

blog/
└── templates/
    └── blog/              # 多一层与应用同名的子目录
        └── index.html

为什么要多一层 blog/？ 因为 APP_DIRS 为 True 时，Django 会在所有应用的 templates/ 目录中查找模板。如果多个应用都有 index.html，就会产生冲突。加上应用名子目录可以有效避免重名。

第三步：配置路由

创建应用级路由 blog/urls.py：

python

复制代码

# 文件路径：blog/urls.py
from django.urls import path
from . import views

# 应用路由表
urlpatterns = [
    path('', views.index, name='index'),   # 空路径匹配 / 首页
]

在项目级 urls.py 中引入：

python

复制代码

# 文件路径：blog_project/urls.py
from django.contrib import admin
from django.urls import path, include          # 导入 include

urlpatterns = [
    path('admin/', admin.site.urls),
    path('', include('blog.urls')),            # 将 blog 应用的路由接入根路径
]

访问验证： 启动服务器，访问 http://127.0.0.1:8000/，页面显示：

text

复制代码

欢迎来到 RUNOOB 博客
这是一个用 Django 构建的个人博客展示站。

九、完整链路梳理

关键点回顾：

项目级 urls.py 通过 include() 分发到应用级 urls.py。
应用级 urls.py 将空路径映射到 views.index。
views.index 使用 render() 加载模板并传入数据。
模板使用 {``{ }} 渲染变量，返回最终 HTML。

十、常见问题排查

问题现象	可能原因	解决方案
`TemplateDoesNotExist`	模板路径或目录结构错误	检查是否在 `templates/blog/` 下
页面 404	路由未配置	检查 `urls.py` 中是否包含 `include('blog.urls')`
应用未生效	未在 `INSTALLED_APPS` 注册	添加 `'blog'`
中文乱码	编码未设置	模板 `<meta charset="UTF-8">`
修改代码不生效	未保存或服务器未重启	检查保存，必要时手动重启
`(venv)` 消失	虚拟环境未激活	重新执行 `source venv/bin/activate`

十一、小结

本章你完成了三件事：

创建虚拟环境并安装 Django：让项目依赖独立，避免版本冲突。
用 startproject / startapp 初始化项目：理解项目与应用的层级结构。
编写 View → Template → URL 的完整链路：掌握 Django 开发的核心模式。

核心收获：

理解 Django 的项目/应用层级结构。
掌握 URL → View → Template 三步走开发模式。
熟悉虚拟环境的使用与 settings.py 的关键配置。

下一篇我们将为博客添加数据模型，实现文章的发布与展示，真正让博客"活"起来。