Python Django入门教程：环境搭建与创建第一个项目

一、准备工作与 Python 虚拟环境配置

Django 是基于 Python 语言构建的高水准 Web 框架。在安装 Django 前，必须确认操作系统中已安装合适版本的 Python 解释器。现代 Django 版本（以 5.x 及主流 LTS 4.2 为例）要求 Python 版本必须大于或等于 3.10。

1. 检查本地 Python 版本

打开系统终端（macOS/Linux 的 Terminal 或 Windows 的 PowerShell/CMD），执行以下命令检查 Python 版本：

python3 --version

Python 3.11.8

如果输出的版本号低于 3.10，或者提示 command not found，需要先从 Python 官方网站下载安装最新的稳定版本，并在安装时勾选“Add Python to PATH”选项。

2. 创建项目工作目录

在磁盘中选择一个合适的位置，新建一个专属于该项目的文件夹，并进入该目录：

mkdir django_demo && cd django_demo

3. 创建并激活虚拟环境（venv）

为什么必须使用虚拟环境？在 Python 开发中，如果不隔离环境，通过 pip 安装的所有第三方包都会写入系统全局目录。当多个项目依赖不同版本的库时，会产生严重的依赖版本冲突；全局安装还需要管理员权限，存在污染系统底层依赖的风险。

使用 Python 内置的 venv 模块在当前目录下创建一个名为 .venv 的虚拟环境：

# 在当前目录下生成专属虚拟环境目录 .venv
python3 -m venv .venv

创建完成后，必须显式激活该环境：

source .venv/bin/activate

.venv\Scripts\Activate.ps1

(.venv) user@host:~/django_demo$

判断激活成功的依据：命令行提示符最前端出现 (.venv) 标记。此时再执行 which python（Windows 下为 where python），输出的路径应当指向当前项目目录下的 .venv，表示后续安装的任何依赖都会严格限制在当前文件夹内。

二、在独立环境中安装 Django 框架

在激活的虚拟环境中，即可使用 pip 安全地安装 Django。为了避免因旧版本 pip 导致安装 wheel 包失败，建议先将 pip 升级至最新版。

1. 升级 pip 并安装 Django

python -m pip install --upgrade pip
pip install django

如果网络环境访问官方 PyPI 速度较慢，可通过 -i 参数指定可信镜像源（例如清华大学镜像源）： pip install django -i https://pypi.tuna.tsinghua.edu.cn/simple。

2. 验证 Django 安装结果

安装完成后，通过调用 Django 内置模块查询版本号，确认安装正确：

python -m django --version

5.0.4

若终端正确打印出版本号（如 5.0.4），说明 Django 核心框架及附属命令行工具（django-admin）已就绪。

三、创建 Django 项目与目录结构解析

Django 提供了一个便捷的脚手架工具 django-admin 用于自动生成标准工程代码骨架。

1. 初始化项目结构

在当前已经处于 django_demo 的目录下，执行以下创建命令：

# 注意：末尾的空格和点号 "." 极其关键
django-admin startproject mysite .

2. 项目目录拓扑与文件职责

执行完上述命令后，使用 ls -la 或 tree 查看当前目录，会生成如下标准结构：

django_demo/
├── .venv/               # 前面创建的虚拟环境文件夹
├── manage.py            # 项目命令行管理实用程序
└── mysite/              # 项目实际的 Python 配置包
    ├── __init__.py      # 空文件，标识该目录为 Python Package
    ├── asgi.py          # ASGI 异步 Web 服务器网关入口
    ├── settings.py      # 项目全局主配置文件
    ├── urls.py          # 顶级路由调度总表
    └── wsgi.py          # WSGI 同步 Web 服务器网关入口

各核心文件的职能定义如下：

• manage.py：一个微型的可执行 Python 脚本，充当开发者与 Django 框架交互的命令行接口。后续的所有开发操作（如运行测试服务器、执行数据库迁移、创建应用等）都通过该脚本触发。它内部会自动关联 mysite.settings 配置。
• mysite/settings.py：整个 Django 工程的“中枢神经”。包含了数据库连接信息（默认为开箱即用的 SQLite3）、已安装的应用列表（INSTALLED_APPS）、中间件管道配置（MIDDLEWARE）、模板路径以及国际化与时区设置。
• mysite/urls.py：站点的根 URL 声明路由表。当用户在浏览器发起 HTTP 请求时，Django 会依次扫描该文件中的 urlpatterns 列表，寻找匹配的 URL 规则并将请求转交对应视图。
• mysite/wsgi.py 与 asgi.py：Web 服务器网关接口标准适配文件。本地调试时由 Django 内置开发服务接管；当部署至生产环境时，WSGI（配合 Gunicorn、uWSGI）或 ASGI（配合 Uvicorn、Daphne）将作为服务进程入口。

四、执行初始数据库迁移并启动开发服务器

Django 自带了一套成熟的对象关系映射系统（ORM）以及认证、会话、后台管理等核心模块。在启动服务器前，了解数据库初始状态至关重要。

1. 执行初始数据库迁移（可选但推荐）

虽然即使不迁移也能直接运行开发服务器，但终端会打印有未应用迁移的警告提示（You have 18 unapplied migration(s)）。这是因为 Django 默认启用了用户认证和权限管理等系统内建表。

在根目录下执行以下命令，完成 SQLite 数据库初始表结构的生成：

python manage.py migrate

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

执行完成后，项目根目录下会自动生成一个名为 db.sqlite3 的本地文件，这是项目的轻量级默认数据库。

2. 启动内置开发服务器

运行以下命令启动 Django 内置的轻量级开发 Web 服务器：

python manage.py runserver

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

System check identified no issues (0 silenced).
October 31, 2026 - 07:15:00
Django version 5.0.4, using settings 'mysite.settings'
Starting development server at http://127.0.0.1:8000/
Quit the server with CONTROL-C.

3. 在浏览器中验证访问

打开本地浏览器，在地址栏输入 http://127.0.0.1:8000/ 并回车。

判断运行成功的依据：如果看到一幅带有小火箭升空图标的页面，并显示“The install worked successfully! Congratulations!”（安装成功！恭喜！），说明 Django 开发环境搭建完全成功，服务器处于正常监听状态。

五、创建第一个应用与编写“Hello Django”视图

在 Django 的设计理念中，项目（Project）与应用（App）有着清晰的职责划分：项目是整个站点的全局容器与配置总合；而应用则是完成特定业务逻辑的独立子模块（如博客、用户中心、购物车等）。一个项目可以包含多个应用。

1. 创建子应用 blog

保持虚拟环境激活，在项目根目录（django_demo）执行以下命令新建一个名为 blog 的应用：

python manage.py startapp blog

执行后，当前目录下会生成一个同名的 blog/ 目录，其中包含 models.py（数据模型）、views.py（业务视图）等文件。

2. 编写第一个视图函数

打开 blog/views.py 文件，清空原有内容，写入一个直接返回 HTTP 字符串响应的视图函数：

from django.http import HttpResponse

def home(request):
    """
    处理客户端请求并返回简单的 HTML 文本响应
    """
    return HttpResponse("<h1>Hello, Django! 这是我的第一个应用页面。</h1>")

3. 配置应用内部路由与全局路由分发

编写完视图函数后，需要建立从 URL 路径到视图函数的映射关系。

第一步：在应用内创建 blog/urls.py 文件：

from django.urls import path
from . import views

urlpatterns = [
    # 匹配空路径，映射至 views.home 视图函数
    path('', views.home, name='home'),
]

第二步：将子应用路由挂载到根路由 mysite/urls.py 中：

打开 mysite/urls.py，使用 include() 函数引入 blog.urls：

from django.contrib import admin
from django.urls import path, include  # 导入 include 函数

urlpatterns = [
    path('admin/', admin.site.urls),
    # 将以 blog/ 开头的访问请求全权指派给 blog 应用内部的 urls.py 调度
    path('blog/', include('blog.urls')),
]

4. 刷新验证运行结果

重新启动或切换回正在运行的服务器终端，在浏览器中访问：

http://127.0.0.1:8000/blog/

判断成功的依据：浏览器页面上直接显示“Hello, Django! 这是我的第一个应用页面。”，并且终端控制台打出状态码 "GET /blog/ HTTP/1.1" 200。这表明从 HTTP 请求进入、URL 正则匹配、视图函数处理到 HTTP 响应输出的全链路已闭环运作。

六、常见新手问题排查与注意事项

初次搭建 Django 项目时，最容易遇到由于环境变量、端口冲突或目录层级引起的问题。以下是核心排查准则：

1. 提示 django-admin: command not found 或模块未找到

原因解释：当前终端尚未激活虚拟环境，或者当前终端会话已关闭，直接在系统全局执行命令，而 Django 仅安装在 .venv 中。
排查方法：观察终端提示符最前列是否有 (.venv)。如果没有，重新执行 source .venv/bin/activate（或 Windows 激活脚本）后再试。

2. 启动服务提示端口被占用 Error: That port is already in use.

原因解释：8000 端口已被先前未正常关闭的 Python 进程或其他本地服务（如开发工具代理、其他 Web 容器）占用。
排查方法：在 runserver 命令后显式指定一个未被占用的端口号，例如启动在 8080 或 8001 端口：

python manage.py runserver 8001

随后通过 http://127.0.0.1:8001/ 即可正常访问。

3. 目录双层嵌套导致找不到 manage.py

原因解释：在执行 startproject mysite 时遗漏了末尾的点号，导致生成了 django_demo/mysite/manage.py，而当前终端处于 django_demo 根目录，执行 python manage.py 就会提示找不到文件。
排查方法：执行 ls 查看当前目录下是否存在 manage.py。若不存在，说明其位于子文件夹内，可进入该子目录操作，或者重新规范初始化。

4. Windows PowerShell 提示脚本执行策略限制

原因解释：PowerShell 默认的安全策略禁止执行未签名的 .ps1 脚本。
排查方法：以管理员身份打开 PowerShell，执行 Set-ExecutionPolicy RemoteSigned -Scope CurrentUser，输入 Y 确认后重新执行激活命令。

七、项目创建全流程与检查清单总结

至此，我们已经完成了 Python Django 的开发环境搭建、项目骨架初始化、开发服务器启动以及首个应用的视图联调。为了在日后创建新项目时形成标准化肌肉记忆，下表将关键生命周期阶段与验证指标梳理成速查矩阵：

完成这些基线工作后，你便拥有了一个结构纯净、配置规范的 Django 基础工程。在此基础上，你可以进一步在 models.py 中定义数据模型，在 templates/ 中引入 HTML 模板，逐步构建出功能完备的现代化 Web 应用。