2026年6月26日 20:10 5 分钟阅读

Django 安装与使用指南

系列：Python Web 框架

第 3 / 11 篇

Django 是一个 Python 全栈 Web 框架，遵循 MVT（Model-View-Template）架构，内置 ORM、后台管理、用户认证、表单处理等功能。它的设计理念是「开箱即用」——不需要额外集成就能快速搭建完整的 Web 应用。

适用环境

Django 需要 Python 3.10 及以上版本（Django 5.2.x）。本文在 Linux 环境下示范，macOS 和 Windows 同样适用。

安装前确认 Python 和 pip 版本：

1
python3 --version
2
pip --version

建议在虚拟环境中操作：

安装 Django

创建项目目录并初始化虚拟环境：

1
mkdir django-demo && cd django-demo
2
python3 -m venv .venv
3
source .venv/bin/activate

激活后终端提示符前会出现 (.venv) 标识。安装 Django：

1
pip install django

安装完成后确认版本：

1
python -m django --version

创建项目

使用 django-admin 创建一个新项目：

1
django-admin startproject mysite .

注意末尾的 . 表示在当前目录创建项目，这样项目文件会直接放在 django-demo/ 下，不会多套一层目录。

创建后的目录结构：

1
django-demo/
2
├── manage.py           # 命令行工具
3
├── mysite/
4
│   ├── __init__.py
5
│   ├── settings.py     # 项目配置
6
│   ├── urls.py         # 根路由
7
│   ├── wsgi.py         # WSGI 入口
8
│   └── asgi.py         # ASGI 入口

启动开发服务器：

1
python manage.py runserver

访问 http://127.0.0.1:8000，看到 Django 欢迎页就说明项目创建成功。

默认监听 127.0.0.1:8000，如需局域网访问可以指定地址和端口：

1
python manage.py runserver 0.0.0.0:8080

创建应用

Django 项目由多个「应用」组成，每个应用负责一块独立功能。创建一个名为 blog 的应用：

1
python manage.py startapp blog

目录结构变为：

1
django-demo/
2
├── manage.py
3
├── mysite/
4
│   └── ...
5
├── blog/
6
│   ├── migrations/     # 数据库迁移文件
7
│   ├── admin.py        # 后台管理配置
8
│   ├── apps.py         # 应用配置
9
│   ├── models.py       # 数据模型
10
│   └── views.py        # 视图逻辑

把应用注册到项目。编辑 mysite/settings.py，在 INSTALLED_APPS 中添加：

1
INSTALLED_APPS = [
2
    'django.contrib.admin',
3
    'django.contrib.auth',
4
    'django.contrib.contenttypes',
5
    'django.contrib.sessions',
6
    'django.contrib.messages',
7
    'django.contrib.staticfiles',
8
    'blog',                     # 新增
9
]

第一个视图

编辑 blog/views.py：

1
from django.http import HttpResponse
2

3

4
def index(request):
5
    return HttpResponse("Hello, Django!")

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

1
from django.urls import path
2
from . import views
3

4
urlpatterns = [
5
    path('', views.index, name='index'),
6
]

然后在项目根路由 mysite/urls.py 中引入：

1
from django.contrib import admin
2
from django.urls import path, include
3

4
urlpatterns = [
5
    path('admin/', admin.site.urls),
6
    path('', include('blog.urls')),
7
]

访问 http://127.0.0.1:8000，页面显示 Hello, Django!。

数据模型与 ORM

在 blog/models.py 中定义文章模型：

1
from django.db import models
2

3

4
class Post(models.Model):
5
    title = models.CharField(max_length=200, verbose_name='标题')
6
    body = models.TextField(verbose_name='正文')
7
    created_at = models.DateTimeField(auto_now_add=True, verbose_name='创建时间')
8
    updated_at = models.DateTimeField(auto_now=True, verbose_name='更新时间')
9

10
    class Meta:
11
        ordering = ['-created_at']
12

13
    def __str__(self):
14
        return self.title

生成迁移文件并应用到数据库：

1
python manage.py makemigrations
2
python manage.py migrate

Django 默认使用 SQLite，数据库文件为项目根目录下的 db.sqlite3，无需额外配置。

在视图中使用 ORM

修改 blog/views.py：

1
from django.http import HttpResponse
2
from .models import Post
3

4

5
def index(request):
6
    posts = Post.objects.all()
7
    lines = [f'<li>{p.title} — {p.created_at:%Y-%m-%d}</li>' for p in posts]
8
    return HttpResponse(f"<ul>{''.join(lines)}</ul>")

通过 shell 添加测试数据

1
python manage.py shell

进入交互式环境：

1
from blog.models import Post
2
Post.objects.create(title='第一篇文章', body='这是正文内容。')
3
Post.objects.create(title='第二篇文章', body='又一篇正文。')
4
Post.objects.all()

刷新页面即可看到文章列表。

使用模板

上面的视图直接把 HTML 写在 Python 代码里，实际项目应当使用模板。在 blog/ 下创建模板目录：

1
mkdir -p blog/templates/blog

创建 blog/templates/blog/index.html：

1
<!DOCTYPE html>
2
<html>
3
<head>
4
    <meta charset="utf-8">
5
    <title>博客</title>
6
</head>
7
<body>
8
    <h1>文章列表</h1>
9
    <ul>
10
        {% for post in posts %}
11
            <li>
12
                <h2>{{ post.title }}</h2>
13
                <p>{{ post.body|truncatechars:100 }}</p>
14
                <small>{{ post.created_at|date:"Y-m-d" }}</small>
15
            </li>
16
        {% empty %}
17
            <li>暂无文章。</li>
18
        {% endfor %}
19
    </ul>
20
</body>
21
</html>

修改 blog/views.py 使用模板渲染：

1
from django.shortcuts import render
2
from .models import Post
3

4

5
def index(request):
6
    posts = Post.objects.all()
7
    return render(request, 'blog/index.html', {'posts': posts})

render 接收三个参数：请求对象、模板路径、上下文数据。模板中 {% for %} 和 {{ }} 是 Django 模板语法的循环和变量输出。

后台管理

Django 自带功能完善的后台管理界面。先创建管理员账号：

1
python manage.py createsuperuser

按提示输入用户名、邮箱和密码。把 Post 模型注册到后台，编辑 blog/admin.py：

1
from django.contrib import admin
2
from .models import Post
3

4

5
@admin.register(Post)
6
class PostAdmin(admin.ModelAdmin):
7
    list_display = ['title', 'created_at', 'updated_at']
8
    search_fields = ['title']

启动服务器后访问 http://127.0.0.1:8000/admin/，用刚才创建的账号登录，即可在后台增删改查文章。

常用命令速查

1
python manage.py runserver           # 启动开发服务器
2
python manage.py startapp appname    # 创建应用
3
python manage.py makemigrations      # 生成迁移文件
4
python manage.py migrate             # 应用迁移
5
python manage.py createsuperuser     # 创建管理员
6
python manage.py shell               # 交互式 Python shell
7
python manage.py collectstatic       # 收集静态文件
8
python manage.py test                # 运行测试
9
python manage.py showmigrations      # 查看迁移状态

常见问题

修改模型后页面报错

修改了 models.py 后需要生成并应用迁移：

1
python manage.py makemigrations
2
python manage.py migrate

如果迁移冲突或出错，可以先查看状态：

1
python manage.py showmigrations

静态文件 404

开发环境下 Django 会自动处理静态文件。如果 404，确认 settings.py 中 INSTALLED_APPS 包含了 django.contrib.staticfiles。

生产环境需要用 collectstatic 收集静态文件并由 Nginx 等服务处理。

模板找不到

Django 默认在每个已注册应用的 templates/ 目录下查找模板。推荐的目录结构是 blog/templates/blog/index.html（加一层应用名的子目录），这样不同应用的模板不会重名冲突。

CSRF 验证失败

POST 表单需要在模板内添加 {% csrf_token %} 标签：

1
<form method="post">
2
    {% csrf_token %}
3
    <!-- 表单字段 -->
4
    <button type="submit">提交</button>
5
</form>

如果是在 API 场景（前后端分离），可以给视图加 @csrf_exempt 装饰器，或使用 DRF（Django REST Framework）等方案。

端口已被占用

开发服务器默认使用 8000 端口，如果冲突可以指定其他端口：

1
python manage.py runserver 8001

pip 安装慢或失败

参考 pip 源的设置和使用配置国内镜像源。

总结

Django 作为全栈框架，优势在于开箱即用和组件齐全。本文覆盖了安装、项目与应用创建、路由配置、ORM 数据操作、模板渲染和后台管理等核心环节，足够搭建一个功能完整的 Web 应用。更多内容可以参考 Django 官方文档。