1.2 开发环境搭建

文档摘要

1.2 Django 开发环境搭建核心摘要：本节系统讲解 Django 开发环境的完整搭建流程，涵盖 Python 环境准备、虚拟环境隔离、Django 框架安装、项目初始化与开发服务器启动五大关键步骤。内容严格遵循 Python 3.8+ 与 Django 4.2+ 最佳实践，强调依赖隔离、版本兼容性与安全性，为后续 Web 应用开发奠定稳定、可复现的基础环境。 1.2.1 Python 环境准备 Django 是基于 Python 构建的 Web 框架，因此 Python 运行时环境是整个开发链路的底层基石。Django 4.2 及以上版本要求 Python 3.8 或更高版本，推荐使用 Python 3.9–3.12 稳定发行版以兼顾性能、安全更新与生态兼容性。 1.2.1.

1.2 Django 开发环境搭建

核心摘要：本节系统讲解 Django 开发环境的完整搭建流程，涵盖 Python 环境准备、虚拟环境隔离、Django 框架安装、项目初始化与开发服务器启动五大关键步骤。内容严格遵循 Python 3.8+ 与 Django 4.2+ 最佳实践，强调依赖隔离、版本兼容性与安全性，为后续 Web 应用开发奠定稳定、可复现的基础环境。

1.2.1 Python 环境准备

Django 是基于 Python 构建的 Web 框架，因此 Python 运行时环境是整个开发链路的底层基石。Django 4.2 及以上版本要求 Python 3.8 或更高版本，推荐使用 Python 3.9–3.12 稳定发行版以兼顾性能、安全更新与生态兼容性。

1.2.1.1 检查 Python 安装状态

在终端中执行以下命令，确认系统是否已预装符合要求的 Python 版本：


python --version

若返回 Command not found 或版本低于 3.8（例如 Python 3.7.17），需升级或安装新版 Python。部分 Linux/macOS 系统默认提供 python3 命令，此时使用：


python3 --version

✅ 成功标志：输出形如 Python 3.11.8 的版本号，且主版本号 ≥ 3.8。

1.2.1.2 安装或升级 Python（以 Python 3.11 为例）

访问 Python 官方下载页面获取对应操作系统的安装包，并按以下规范操作：

操作系统	关键操作说明
Windows	运行 `.exe` 安装程序时，必须勾选 “Add Python to PATH”；建议启用 “Install pip” 和 “Add Python to environment variables”；安装路径可保留默认，避免含空格或中文路径。
macOS	下载 `.pkg` 安装包，双击完成安装；安装后默认启用 `python3` 和 `pip3` 命令，系统原生 Python 2（已弃用）不受影响。
Linux（Ubuntu/Debian）	执行以下命令更新并安装最新稳定版： `bash<br>sudo apt update && sudo apt install -y python3.11 python3.11-venv python3.11-pip<br>` 验证安装： `bash<br>python3.11 --version && python3.11 -m pip --version<br>`

安装完成后，统一验证 pip 是否可用（pip 是 Python 包管理核心工具，Django 依赖其安装）：


python3.11 -m pip --version  # 推荐方式，避免 pip 版本错配
# 或
pip3 --version

✅ 成功标志：输出 pip X.Y.Z from ... (python 3.X)，表明 pip 已与 Python 解释器正确绑定。

1.2.2 虚拟环境创建与管理（venv）

虚拟环境是 Python 项目工程化的强制规范。它通过隔离解释器、标准库与第三方包，确保不同 Django 项目可并行运行于互不干扰的依赖环境中，彻底规避 django==4.1 与 django==4.2 冲突等典型问题。

1.2.2.1 创建虚拟环境

在项目根目录（如 ~/workspace/django-projects/）中执行：


python3.11 -m venv venv

该命令将创建名为 venv 的子目录，内含独立 Python 解释器、pip 及基础库。目录名可自定义（如 env、.venv），但 venv 是社区通用约定。

💡 提示：python3.11 -m venv 显式指定解释器版本，避免因 python 指向旧版本导致环境创建失败。

1.2.2.2 激活虚拟环境

系统	激活命令	激活后提示符示例
Windows (PowerShell)	`venv\Scripts\Activate.ps1` （首次运行需执行 `Set-ExecutionPolicy RemoteSigned -Scope CurrentUser`）	`(venv) PS C:\path\to\project>`
Windows (CMD)	`venv\Scripts\activate.bat`	`(venv) C:\path\to\project>`
macOS / Linux	`source venv/bin/activate`	`(venv) user@host:~/project$`

✅ 成功标志：终端提示符前出现 (venv) 前缀，且 which python（macOS/Linux）或 where python（Windows）返回路径指向 venv 目录内。

1.2.2.3 虚拟环境结构图示

图 1.2.1：虚拟环境隔离机制示意图
虚拟环境通过复制解释器与重定向 pip，构建出与全局环境完全解耦的运行沙箱。所有 pip install 均仅影响 venv/Lib/site-packages/，保障项目可移植性与协作一致性。

1.2.2.4 停用与最佳实践

停用命令：在任意目录下执行 deactivate，提示符前缀 (venv) 消失即生效。
核心实践：
- ✅ 每个项目独享一个虚拟环境（禁止跨项目复用）；
- ✅ 虚拟环境目录置于项目根目录下（如 ./venv），便于 Git 忽略；
- ✅ 在 .gitignore 中添加 venv/、.venv/、env/ 等条目，防止二进制文件污染仓库；
- ✅ 使用 python -m pip list 查看当前环境已安装包，避免全局污染。

1.2.3 安装 Django 框架

确保虚拟环境已激活（提示符含 (venv)），执行：


pip install Django==4.2.11

🔒 推荐指定版本号：Django==4.2.11（LTS 版本，长期支持至 2026 年 4 月），避免 pip install Django 安装非 LTS 的预发布版（如 5.0a1）导致兼容性风险。

安装完成后验证：


python -m django --version  # 输出：4.2.11
django-admin --version       # 输出：4.2.11

✅ 成功标志：版本号与安装指令完全一致，且 django-admin 命令可全局调用。

1.2.4 创建 Django 项目骨架

在虚拟环境激活状态下，进入目标工作目录（如 ~/workspace/django-projects/），执行：


django-admin startproject mysite .

⚠️ 关键细节：末尾的 . 表示在当前目录创建项目（避免生成嵌套目录 mysite/mysite/）。项目名 mysite 需满足：仅含小写字母、数字、下划线；不可以数字开头；避免使用 Python 关键字（如 list, class）。

生成的标准结构如下：


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

文件/目录	作用说明
`manage.py`	项目管理入口脚本，封装 `django-admin` 功能（如 `runserver`, `migrate`, `startapp`）
`mysite/`（内层）	Python 包，承载项目级配置
`settings.py`	核心配置文件：数据库、静态文件、中间件、已注册应用、安全密钥等
`urls.py`	路由中枢：定义 URL 模式与视图函数/类的映射关系
`asgi.py` / `wsgi.py`	生产部署入口：ASGI（异步）与 WSGI（同步）服务器适配器
`__init__.py`	标识该目录为 Python 包（空文件即可）

Django 项目结构图示

图 1.2.2：Django 项目标准目录结构
manage.py 作为操作枢纽，mysite/ 子包封装所有配置逻辑。理解此结构是后续配置 settings.py、调试路由 urls.py 及部署 wsgi.py 的前提。

1.2.5 启动开发服务器并验证

进入 mysite/ 目录（含 manage.py 的路径），执行：


python manage.py runserver

终端将输出：


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 by running 'python manage.py migrate'.
July 15, 2024 - 14:30:00
Django version 4.2.11, using settings 'mysite.settings'
Starting development server at http://127.0.0.1:8000/
Quit the server with CONTROL-C.

✅ 成功标志：访问 http://127.0.0.1:8000/ 或 http://localhost:8000/，页面显示 “It worked!” 与 “Congratulations on your first Django-powered page!”。

开发服务器高级用法

场景	命令	说明
更改端口	`python manage.py runserver 8080`	监听 `http://127.0.0.1:8080/`
允许局域网访问	`python manage.py runserver 0.0.0.0:8000`	其他设备通过 `http://[本机IP]:8000/` 访问（仅限可信网络）
指定配置文件	`python manage.py runserver --settings=mysite.settings_dev`	加载自定义 settings 模块

⚠️ 重要安全提示：runserver 仅用于开发调试。禁止在生产环境使用。生产部署需搭配 Nginx + Gunicorn/uWSGI 架构，确保并发处理能力、静态文件服务与安全加固。

1.2.6 本章总结：Django 开发环境搭建全流程

步骤	关键操作	验证方法	SEO 核心关键词
1. Python 环境	安装 Python 3.8+，启用 `pip`	`python3.11 --version` & `pip --version`	`Python 3.11 安装`, `Django 环境依赖`
2. 虚拟环境	`python3.11 -m venv venv` → `source venv/bin/activate`	提示符含 `(venv)`，`which python` 指向 `venv`	`Django 虚拟环境`, `Python venv 隔离`
3. Django 安装	`pip install Django==4.2.11`	`python -m django --version` 返回 `4.2.11`	`安装 Django 4.2`, `Django pip 安装`
4. 项目创建	`django-admin startproject mysite .`	目录结构符合标准，`manage.py` 可执行	`Django 创建项目`, `startproject 命令`
5. 服务验证	`python manage.py runserver` → 浏览器访问 `localhost:8000`	显示 Django 欢迎页	`Django 开发服务器`, `runserver 启动`

环境搭建完成即代表开发就绪。后续章节将基于此稳定环境，深入讲解 Django 应用（App）设计、模型（Model）定义、视图（View）开发与模板（Template）渲染等核心机制。所有操作均在隔离虚拟环境中进行，确保学习过程零冲突、可复现、易回溯。