从零开始学习Python Django：从环境搭建到第一个 Web 应用

前言：为什么选择 Django？

在众多 Python Web 框架中，Django 一直占据着重要地位。作为一个 "batteries-included"（内置电池）的框架，它提供了完整的解决方案，从数据库交互到用户认证，从表单处理到后台管理，几乎涵盖了 Web 开发的方方面面。

对于初学者来说，Django 有几个显著优势：

• 严格的 MVC 架构（在 Django 中称为 MVT）让代码组织更规范
• 内置的管理后台可以快速实现数据管理功能
• 强大的 ORM 系统简化数据库操作，无需编写 SQL
• 完善的文档和活跃的社区支持
• 丰富的第三方库和插件生态

本教程将带领你从零开始，假设你尚未安装 Python，一步步搭建 Django 开发环境，并创建你的第一个 Django 应用。

第一步：安装 Python

Django 是基于 Python 的 Web 框架，因此首先需要安装 Python 环境。

Windows 系统安装 Python

1. 访问 Python 官方网站：https://www.python.org/downloads/
2. 点击 "Download Python X.X.X" 按钮（X.X.X 是最新版本号）
3. 运行下载的安装程序
4. 重要：在安装界面勾选 "Add Python to PATH" 选项，这将把 Python 添加到系统环境变量中，方便后续在命令行中使用
5. 点击 "Install Now" 进行默认安装，或选择 "Customize installation" 进行自定义安装
6. 安装完成后，可以点击 "Disable path length limit" 来解除 Windows 的路径长度限制（推荐）

macOS 系统安装 Python

macOS 通常预装了 Python，但可能不是最新版本。推荐使用 Homebrew 安装：

1. 首先安装 Homebrew（如果尚未安装）：

   打开终端，输入以下命令：

   /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

2. 使用 Homebrew 安装 Python：

   brew install python

Linux 系统安装 Python

大多数 Linux 发行版都预装了 Python，你可以通过以下命令检查版本：

python3 --version

如果需要安装或升级，可以使用发行版的包管理器：

Ubuntu/Debian：

sudo apt update
sudo apt install python3 python3-pip

Fedora/RHEL：

sudo dnf install python3 python3-pip

验证 Python 安装

安装完成后，验证是否安装成功：

1. 打开命令提示符（Windows）或终端（macOS/Linux）

2. 输入以下命令检查 Python 版本：

   python --version  # Windows 通常使用这个命令
   # 或
   python3 --version  # macOS/Linux 通常使用这个命令

3. 你应该能看到类似这样的输出：Python 3.10.6（版本号可能不同）

4. 同样验证 pip（Python 包管理工具）是否安装：

   pip --version
   # 或
   pip3 --version

   注意：在不同系统中，Python 3 可能需要使用 python3 命令，而 pip 可能需要使用 pip3。为了方便，后续教程中我会统一使用 python 和 pip，如果你的系统需要区分，请相应替换。

第二步：设置虚拟环境

在开始 Django 开发之前，强烈建议使用虚拟环境。虚拟环境可以为每个项目创建独立的 Python 环境，避免不同项目之间的依赖冲突。

什么是虚拟环境？为什么需要它？

虚拟环境是一个隔离的目录，包含了一个特定版本的 Python 和一些额外的包。使用虚拟环境有以下好处：

• 可以为不同项目使用不同版本的 Python 包，避免版本冲突
• 便于项目迁移和部署
• 保持全局 Python 环境的清洁
• 方便记录和管理项目依赖

创建虚拟环境

1. 首先，选择一个目录来存放你的 Django 项目，例如在用户目录下创建一个 django_projects 文件夹：

   # 创建项目文件夹
   mkdir django_projects
   cd django_projects

2. 创建虚拟环境：

   Python 3.3+ 内置了 venv 模块，可以直接使用：

   # 创建名为 venv 的虚拟环境
   python -m venv venv

   这条命令会在当前目录下创建一个名为 venv 的文件夹，里面包含了一个独立的 Python 环境。

激活虚拟环境

创建完成后，需要激活虚拟环境：

• Windows（命令提示符）：

  venv\Scripts\activate

• Windows（PowerShell）：

  .\venv\Scripts\Activate.ps1

• macOS/Linux（bash/zsh）：

  source venv/bin/activate

  激活成功后，你会看到命令行提示符前出现 (venv) 字样，表示当前处于虚拟环境中。

退出虚拟环境

当你完成工作需要退出虚拟环境时，可以使用以下命令：

deactivate

注意：每次开始工作时，都需要进入项目目录并激活虚拟环境。这是一个良好的开发习惯，建议严格遵守。

第三步：安装 Django

在激活的虚拟环境中，使用 pip 安装 Django 非常简单：

pip install django

这条命令会安装最新版本的 Django。如果你需要特定版本，可以指定版本号：

pip install django==4.2.7  # 安装 4.2.7 版本

安装完成后，验证 Django 是否安装成功：

django-admin --version

如果看到版本号输出（如 4.2.7），说明 Django 已成功安装。

个人观点：对于生产环境，我建议指定 Django 版本，以确保项目的稳定性。Django 每个 LTS（长期支持）版本会提供 3 年的安全更新，是生产环境的理想选择。当前最新的 LTS 版本是 4.2.x。

第四步：创建第一个 Django 项目

Django 提供了一个命令行工具 django-admin 来帮助我们创建和管理项目。

创建项目

在虚拟环境激活的状态下，执行以下命令创建一个名为 myfirstproject 的 Django 项目：

django-admin startproject myfirstproject

这条命令会创建一个名为 myfirstproject 的文件夹，里面包含了 Django 项目的基本结构：

myfirstproject/
├── manage.py
└── myfirstproject/
    ├── __init__.py
    ├── asgi.py
    ├── settings.py
    ├── urls.py
    └── wsgi.py

让我们解释一下这些文件和目录的作用：

• manage.py：一个命令行工具，用于与 Django 项目交互，比如启动服务器、创建应用等
• myfirstproject/：项目的主目录，包含项目的配置文件
  • __init__.py：空文件，告诉 Python 这是一个 Python 包
  • settings.py：项目的设置文件，包含数据库配置、应用列表等
  • urls.py：项目的 URL 配置，定义 URL 路由规则
  • asgi.py：用于 ASGI 兼容的 Web 服务器的配置
  • wsgi.py：用于 WSGI 兼容的 Web 服务器的配置

进入项目目录

创建完成后，进入项目目录：

cd myfirstproject

现在，我们所有的操作都将在这个目录下进行。

第五步：了解 Django 项目结构和配置

在开始编写代码之前，让我们先了解一下 Django 项目的核心配置文件 settings.py。

使用你喜欢的文本编辑器或 IDE 打开 myfirstproject/settings.py 文件。这里推荐一些常用的编辑器：VS Code、PyCharm、Sublime Text 等。

关键配置项解析

1. DEBUG：调试模式开关。在开发阶段设置为 True，可以显示详细的错误信息；在生产环境必须设置为 False。

2. ALLOWED_HOSTS：允许访问的主机列表。在开发阶段可以留空或设置为 ['localhost', '127.0.0.1']；在生产环境需要设置为实际的域名。

3. INSTALLED_APPS：项目中安装的应用列表。Django 默认已经包含了一些内置应用，如 django.contrib.admin（管理后台）、django.contrib.auth（用户认证）等。

4. DATABASES：数据库配置。Django 默认使用 SQLite 数据库，这对于开发非常方便，无需额外配置。在生产环境中，你可能需要切换到 PostgreSQL、MySQL 等数据库。

5. STATIC_URL：静态文件（CSS、JavaScript、图片等）的 URL 前缀。

个人观点：在开发初期，建议保持默认配置不变。随着项目的发展，再根据实际需求修改这些配置。特别是 DEBUG 选项，在部署到生产环境前一定要记得关闭，否则可能会泄露敏感信息。

第六步：运行 Django 开发服务器

Django 内置了一个开发用的 Web 服务器，方便我们在开发过程中预览和测试应用。

在项目目录下（包含 manage.py 的目录），执行以下命令：

python manage.py runserver

如果一切正常，你会看到类似以下的输出：

Watching for file changes with StatReloader
Performing system checks...

System check identified no issues (0 silenced).

You have 18 unapplied migration(s). Your project may not work properly until you apply the migrations for app(s): admin, auth, contenttypes, sessions.
Run 'python manage.py migrate' to apply them.
October 06, 2025 - 10:00:00
Django version 4.2.7, using settings 'myfirstproject.settings'
Starting development server at http://127.0.0.1:8000/
Quit the server with CTRL-BREAK.

这表示开发服务器已经启动，默认运行在 http://127.0.0.1:8000/（本地主机的 8000 端口）。

现在，打开你的浏览器，访问 http://127.0.0.1:8000/，你应该能看到 Django 的欢迎页面，上面写着 "Congratulations on your first Django-powered page!"。

注意：开发服务器仅用于开发环境，不适合用于生产环境。它的性能和安全性都不满足生产环境的要求。

自定义服务器端口

如果 8000 端口被占用，或者你想使用其他端口，可以在启动服务器时指定端口：

python manage.py runserver 8080  # 使用 8080 端口

也可以指定允许访问的 IP 地址：

python manage.py runserver 0.0.0.0:8000  # 允许局域网内其他设备访问

停止服务器

要停止开发服务器，在命令行中按 Ctrl + C（Windows/Linux）或 Cmd + C（macOS）。

第七步：创建 Django 应用

Django 项目由一个或多个应用（app）组成。应用是功能的集合，例如一个博客项目可能包含用户认证应用、文章管理应用、评论应用等。

让我们创建一个名为 myfirstapp 的应用：

1. 确保你仍在项目目录下（包含 manage.py 的目录），并且虚拟环境已激活

2. 执行以下命令：

   myfirstapp/
   ├── __init__.py
   ├── admin.py
   ├── apps.py
   ├── migrations/
   │   └── __init__.py
   ├── models.py
   ├── tests.py
   └── views.py

   这些文件的作用：

• __init__.py：空文件，标识这是一个 Python 包
• admin.py：用于配置 Django 管理后台
• apps.py：应用的配置
• migrations/：存放数据库迁移文件
• models.py：定义数据模型
• tests.py：用于编写测试代码
• views.py：定义视图函数，处理用户请求

在项目中注册应用

创建应用后，需要在项目中注册它，这样 Django 才会识别这个应用。

打开 myfirstproject/settings.py 文件，找到 INSTALLED_APPS 列表，添加我们的应用：

INSTALLED_APPS = [
    'django.contrib.admin',
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'django.contrib.messages',
    'django.contrib.staticfiles',
    'myfirstapp',  # 添加这一行，注册我们的应用
]

个人观点：将应用模块化是 Django 的一个优秀设计。这种结构使代码更有条理，便于维护和扩展。在实际开发中，建议根据功能划分应用，每个应用专注于解决特定的问题。

第八步：创建第一个视图

视图是处理用户请求并返回响应的函数或类。让我们创建一个简单的视图。

打开 myfirstapp/views.py 文件，添加以下代码：

from django.http import HttpResponse

def home(request):
    """首页视图函数"""
    return HttpResponse("Hello, Django! 这是我的第一个 Django 应用。")

这个简单的视图函数接收一个 request 参数（表示用户的请求），并返回一个包含 "Hello, Django! 这是我的第一个 Django 应用。" 文本的响应。

第九步：配置 URL 路由

现在我们有了视图，还需要配置 URL 路由，告诉 Django 当用户访问某个 URL 时应该调用哪个视图。

应用级 URL 配置

首先，在 myfirstapp 目录下创建一个名为 urls.py 的文件，添加以下代码：

from django.urls import path
from . import views

urlpatterns = [
    path('', views.home, name='home'),
]

这段代码定义了应用级的 URL 路由：

• 当用户访问应用的根路径（''）时，调用 views.home 视图函数
• name='home' 给这个路由起了一个名字，方便在模板中引用

项目级 URL 配置

接下来，需要将应用的 URL 配置添加到项目的 URL 配置中。

打开 myfirstproject/urls.py 文件，修改为以下内容：

from django.contrib import admin
from django.urls import include, path

urlpatterns = [
    path('admin/', admin.site.urls),
    path('', include('myfirstapp.urls')),  # 添加这一行，包含应用的 URL 配置
]

这里我们使用 include 函数将 myfirstapp.urls 包含进来，意味着当用户访问网站根路径时，会使用 myfirstapp 应用的 URL 配置。

第十步：测试我们的第一个视图

现在，让我们启动开发服务器，测试一下我们创建的视图：

python manage.py runserver

访问 http://127.0.0.1:8000/，你应该能看到我们在视图中定义的文本："Hello, Django! 这是我的第一个 Django 应用。"

恭喜！你已经成功创建了第一个 Django 应用，并显示了一个简单的页面。

第十一步：创建数据模型

Django 的 ORM（对象关系映射）系统允许我们使用 Python 类来定义数据库结构，而无需直接编写 SQL。

让我们创建一个简单的 Article 模型，用于存储文章信息。

打开 myfirstapp/models.py 文件，添加以下代码：

from django.db import models
from django.utils import timezone

class Article(models.Model):
    """文章模型"""
    title = models.CharField(max_length=200)  # 文章标题，最大长度 200
    content = models.TextField()  # 文章内容
    created_at = models.DateTimeField(default=timezone.now)  # 创建时间，默认为当前时间
    published = models.BooleanField(default=False)  # 是否发布，默认为 False

    def __str__(self):
        """返回模型的字符串表示，通常用于管理后台"""
        return self.title

这个模型定义了一个文章实体，包含以下字段：

• title：文章标题，使用 CharField 表示短文本
• content：文章内容，使用 TextField 表示长文本
• created_at：创建时间，使用 DateTimeField
• published：是否发布，使用 BooleanField 表示布尔值

__str__ 方法定义了模型实例的字符串表示，这在管理后台中会很有用。

第十二步：数据库迁移

定义好模型后，我们需要将模型映射到数据库中。Django 使用迁移（migrations）来管理数据库结构的变化。

创建迁移文件

首先，创建迁移文件：

python manage.py makemigrations myfirstapp

这条命令会根据模型的变化生成迁移文件，输出类似：

Migrations for 'myfirstapp':
  myfirstapp/migrations/0001_initial.py
    - Create model Article

应用迁移

然后，将迁移应用到数据库：

python manage.py migrate

这条命令会执行所有未应用的迁移，包括 Django 内置应用的迁移和我们刚刚创建的迁移。输出类似：

Operations to perform:
  Apply all migrations: admin, auth, contenttypes, myfirstapp, sessions
Running migrations:
  Applying contenttypes.0001_initial... OK
  Applying auth.0001_initial... OK
  ...
  Applying myfirstapp.0001_initial... OK
  Applying sessions.0001_initial... OK

现在，我们的 Article 模型已经被创建到数据库中了。

个人观点：Django 的迁移系统是其一大亮点。它允许我们像版本控制代码一样管理数据库结构的变化，使团队协作和部署变得更加简单。每次修改模型后，都应该创建并应用迁移。

第十三步：使用 Django 管理后台

Django 提供了一个强大的自动生成的管理后台，让我们可以轻松地管理数据。

创建超级用户

首先，需要创建一个超级用户（管理员）来登录管理后台：

python manage.py createsuperuser

按照提示输入用户名、电子邮件和密码：

Username (leave blank to use 'yourusername'): admin
Email address: admin@example.com
Password:  # 输入密码，输入时不会显示
Password (again):  # 再次输入密码
Superuser created successfully.

注册模型到管理后台

要在管理后台中管理我们的 Article 模型，需要将其注册到管理后台。

打开 myfirstapp/admin.py 文件，添加以下代码：

from django.contrib import admin
from .models import Article

# 注册 Article 模型
admin.site.register(Article)

访问管理后台

启动开发服务器：

python manage.py runserver

访问 http://127.0.0.1:8000/admin/，使用刚才创建的超级用户登录。

登录后，你会看到 Django 管理后台的界面，其中包含了我们注册的 Article 模型。你可以点击 "Articles" 进入文章管理页面，尝试添加、编辑和删除文章。

提示：Django 管理后台非常强大，你可以通过自定义 ModelAdmin 类来定制管理界面的外观和行为。例如，你可以指定列表中显示哪些字段，添加搜索功能等。

第十四步：创建模板显示文章列表

目前我们的首页只显示了一句静态文本。让我们修改它，使其显示所有已发布的文章列表。

创建模板目录

首先，在 myfirstapp 目录下创建一个 templates 目录，然后在 templates 目录下再创建一个 myfirstapp 目录：

mkdir -p myfirstapp/templates/myfirstapp

这样做的目的是避免不同应用的模板文件重名冲突。Django 会自动在每个应用的 templates 目录中查找模板文件。

创建模板文件

在 myfirstapp/templates/myfirstapp 目录下创建一个名为 home.html 的文件，添加以下内容：

<!DOCTYPE html>
<html>
<head>
    <title>我的 Django 博客</title>
    <meta charset="utf-8">
    <style>
        body {
            font-family: Arial, sans-serif;
            max-width: 800px;
            margin: 0 auto;
            padding: 20px;
        }
        .article {
            margin-bottom: 30px;
            padding-bottom: 20px;
            border-bottom: 1px solid #eee;
        }
        .article h2 {
            margin-bottom: 5px;
        }
        .date {
            color: #666;
            font-size: 0.9em;
            margin-bottom: 10px;
        }
    </style>
</head>
<body>
    <h1>我的博客文章</h1>
    
    {% if articles %}
        {% for article in articles %}
            <div class="article">
                <h2>{{ article.title }}</h2>
                <div class="date">{{ article.created_at|date:"Y年m月d日 H:i" }}</div>
                <p>{{ article.content|truncatechars:200 }}</p>
            </div>
        {% endfor %}
    {% else %}
        <p>还没有发布的文章。</p>
    {% endif %}
</body>
</html>

这是一个简单的 HTML 模板，使用了 Django 的模板语法：

• {% if articles %}：条件判断，如果有文章则显示文章列表
• {% for article in articles %}：循环遍历文章列表
• {``{ article.title }}：显示文章标题
• {``{ article.created_at|date:"Y年m月d日 H:i" }}：显示格式化后的创建时间，|date 是一个模板过滤器
• {``{ article.content|truncatechars:200 }}：显示文章内容的前 200 个字符

修改视图使用模板

现在，修改 myfirstapp/views.py 中的 home 视图，使其查询数据库并使用模板：

from django.shortcuts import render
from .models import Article

def home(request):
    """首页视图函数，显示已发布的文章列表"""
    # 查询所有已发布的文章，并按创建时间倒序排列
    articles = Article.objects.filter(published=True).order_by('-created_at')
    
    # 将文章列表传递给模板
    return render(request, 'myfirstapp/home.html', {'articles': articles})

这里我们使用了 render 函数，它会加载指定的模板，并将数据传递给模板。Article.objects.filter(published=True) 用于查询所有已发布的文章。

测试效果

现在，访问 http://127.0.0.1:8000/，你会看到一个简单的博客首页。如果之前在管理后台添加了已发布的文章，它们会显示在这里；如果没有，会显示 "还没有发布的文章。"。

尝试在管理后台添加几篇已发布的文章，然后刷新首页，看看效果。

第十五步：添加更多功能

让我们为应用添加一个显示单篇文章详情的功能。

创建详情视图

在 myfirstapp/views.py 中添加一个 article_detail 视图：

from django.shortcuts import render, get_object_or_404
from .models import Article

# ... 之前的 home 视图保持不变 ...

def article_detail(request, pk):
    """文章详情视图，显示单篇文章的完整内容"""
    # 根据主键查询文章，如果不存在则返回 404 错误
    article = get_object_or_404(Article, pk=pk)
    return render(request, 'myfirstapp/article_detail.html', {'article': article})

get_object_or_404 函数会根据主键（pk）查询文章，如果找不到对应的文章，会返回 404 错误页面。

创建详情页模板

在 myfirstapp/templates/myfirstapp 目录下创建 article_detail.html 文件：

<!DOCTYPE html>
<html>
<head>
    <title>{{ article.title }} - 我的 Django 博客</title>
    <meta charset="utf-8">
    <style>
        body {
            font-family: Arial, sans-serif;
            max-width: 800px;
            margin: 0 auto;
            padding: 20px;
        }
        .date {
            color: #666;
            font-size: 0.9em;
            margin-bottom: 20px;
        }
        .content {
            line-height: 1.6;
        }
        .back-link {
            margin-top: 30px;
            display: inline-block;
        }
    </style>
</head>
<body>
    <h1>{{ article.title }}</h1>
    <div class="date">{{ article.created_at|date:"Y年m月d日 H:i" }}</div>
    <div class="content">{{ article.content|linebreaks }}</div>
    
    <div class="back-link">
        <a href="{% url 'home' %}">返回首页</a>
    </div>
</body>
</html>

{``{ article.content|linebreaks }} 会将文章内容中的换行符转换为 HTML 的 <br> 或 <p> 标签。{% url 'home' %} 使用了我们之前定义的路由名称，生成首页的 URL。

添加详情页 URL 路由

修改 myfirstapp/urls.py，添加详情页的路由：

from django.urls import path
from . import views

urlpatterns = [
    path('', views.home, name='home'),
    path('article/<int:pk>/', views.article_detail, name='article_detail'),
]

<int:pk> 表示这是一个整数类型的参数，会被传递给 article_detail 视图的 pk 参数。

修改首页模板，添加文章链接

修改 home.html，为每篇文章的标题添加链接，指向详情页：

<!-- ... 其他内容保持不变 ... -->
<h2><a href="{% url 'article_detail' article.pk %}">{{ article.title }}</a></h2>
<!-- ... 其他内容保持不变 ... -->

现在，访问首页，点击文章标题，会跳转到该文章的详情页。

总结与下一步学习建议

恭喜你！通过本教程，你已经完成了以下内容：

1. 安装了 Python 和 Django
2. 学习了如何使用虚拟环境
3. 创建了第一个 Django 项目和应用
4. 学习了 Django 的基本结构和配置
5. 创建了视图、模板和 URL 路由
6. 定义了数据模型并使用了数据库迁移
7. 使用 Django 管理后台管理数据
8. 实现了一个简单的博客功能，包括文章列表和详情页

这只是 Django 学习的开始。Django 还有很多强大的功能等待你去探索：

• 用户认证系统：实现用户注册、登录、权限管理等
• 表单处理：创建和处理各种表单，包括数据验证
• 高级模型操作：学习更多查询方法、关系模型等
• 静态文件管理：处理 CSS、JavaScript、图片等静态资源
• 测试：编写单元测试和集成测试
• 部署：将 Django 应用部署到生产服务器

个人观点：学习 Django 最好的方法是动手实践。选择一个小项目（如个人博客、待办事项应用等），逐步实现其功能。遇到问题时，查阅 Django 官方文档（https://docs.djangoproject.com/），它是最权威、最全面的学习资源。

祝你在 Django 的学习之旅中取得进步！如果你有任何问题，欢迎在评论区留言讨论。

（下一篇介绍Django REST Framework，构建强大的Web API）