大家好我是你们的技术博主。今天咱们正式开启Django 快速入门系列的第一篇Django 安装与测试。很多刚接触 Python Web 开发的朋友总是卡在第一步——环境装好了却不知道怎么验证是否装对项目创建了却搞不懂每个文件是干什么的写了个接口也不知道怎么测试。这篇文章会把你从零带到能独立创建项目、启动服务、编写并运行第一个测试用例。整个流程完全本地化操作不需要部署到服务器非常适合新手建立完整认知。1. Django 是什么为什么人人都说它适合快速开发先解决一个最基础的问题Django 到底是什么它解决了什么问题1.1 通俗理解Django 是一个“全家桶”式 Web 框架如果你用纯 Python 写一个网站你需要自己处理 HTTP 请求、路由分发、数据库连接、表单校验、用户认证……这些工作非常繁琐且容易出错。Django 做的事情就是把这些高频重复的“脏活累活”全部封装好让你专注于业务逻辑而不是底层协议。你可以把 Django 理解成一个装修好的精装房水电、墙面、地板、门窗已经给你做好了你要做的是选家具、摆装饰而不是从砌砖开始盖房子。1.2 专业定义与核心特性用更专业的语言来描述Django 是一个基于 Python 的高级 Web 开发框架它鼓励快速开发和干净、实用的设计。它有几个重要的核心特性这也是它在国内开发者中使用广泛的原因MTV 架构模式Django 使用 Model模型、Template模板、View视图的分层思想。Model 负责和数据库打交道Template 负责页面展示View 负责业务逻辑处理。自带 Admin 后台只需要简单的配置你就可以获得一个完整的后台管理系统直接对数据库进行增删改查极大提高了开发效率。ORM 对象关系映射你不需要写复杂的 SQL 语句Django 会帮你在 Python 类和数据库表之间建立映射关系让数据库操作变得像操作普通 Python 对象一样简单。强大的 URL 路由系统用清晰、优雅的 URL 来设计你的 Web 应用而不是类似.php?id123这种丑陋的查询字符串。自带安全防护Django 内置了针对 SQL 注入、XSS 跨站脚本攻击、CSRF 跨站请求伪造等常见网络攻击的防护机制。1.3 哪些场景在用 DjangoDjango 在国内的使用范围非常广从个人博客到企业级应用都有它的身影内容管理系统CMS社交平台新闻资讯网站电商平台数据分析平台的后端 API 服务企业内部管理系统作为系列教程的第一篇我们先把地基打牢。只有把环境安装和基础测试跑通后续的模型、视图、模板、Admin 等高级内容才能顺利展开。2. 环境准备与版本说明在动手安装之前我们要把环境信息明确下来。很多报错都是因为环境不一致导致的比如有人在 Windows 上装好了有人在 Linux 上照着同样的命令执行却失败了。2.1 操作系统与 Python 版本本文的实操示例在 Windows 10/11 和 Ubuntu 20.04/22.04 上均可正常运行。Django 是纯 Python 编写的 Web 框架对操作系统没有强依赖只要 Python 能运行Django 就能运行。Python 版本要求Django 4.x 系列要求 Python 3.8 及以上版本。Django 5.x 系列要求 Python 3.10 及以上版本。这里有两个方案供选择环境项推荐方案说明Python 版本Python 3.10 或 3.11兼容性最好生态最成熟Django 版本Django 4.2 LTS 或 5.0.x建议使用 LTS 长期支持版包管理工具pipPython 官方自带的包管理工具虚拟环境venv 或 virtualenv强烈建议使用隔离项目依赖如果你目前还没有安装 Python需要先去 Python 官网下载对应版本。安装时务必勾选Add Python to PATH选项否则后续命令行中无法直接使用python命令。验证 Python 是否安装成功python --version在大多数环境中你应该能看到类似下面的输出Python 3.11.92.2 为什么强烈建议使用虚拟环境在 Python 开发中虚拟环境是一个非常重要的概念。它就像一个独立的“小房间”每个项目可以在自己的房间里安装各自的依赖包互不干扰。举个例子项目 A 用的是 Django 3.2项目 B 需要用 Django 5.0如果没有虚拟环境这两个版本会在全局环境中相互冲突。有了虚拟环境项目 A 和项目 B 各自拥有独立的依赖库完美隔离。2.3 创建并激活虚拟环境下面我们使用 Python 自带的 venv 模块来创建虚拟环境。Windows 平台# 创建一个名为 venv 的虚拟环境目录 python -m venv venv # 激活虚拟环境 venv\Scripts\activateLinux / macOS 平台# 创建虚拟环境 python3 -m venv venv # 激活虚拟环境 source venv/bin/activate激活成功后命令行提示符会出现(venv)前缀例如(venv) C:\Users\Administrator\myblog这表示你已经进入了虚拟环境接下来安装的所有 Python 包都会被隔离在当前项目中。第一次使用虚拟环境的读者如果遇到激活失败或找不到 activate 脚本的情况可能需要检查一下 Python 安装时是否完整安装了 pip 和 venv 模块。3. 安装 Django 并验证版本环境准备好后我们正式开始安装 Django。3.1 使用 pip 安装 Django确保虚拟环境已经激活然后执行以下命令pip install django这个命令会从 PyPI 官方仓库下载最新稳定版的 Django 并自动安装。如果你希望安装指定版本可以使用pip install django4.2.16如果网络速度不理想可以换成国内镜像源pip install django -i https://pypi.tuna.tsinghua.edu.cn/simple3.2 验证安装结果安装完成后我们通过两个方式来确认 Django 是否真正安装成功。方式一查看版本号python -m django --version如果输出一个版本号例如4.2.16或5.0.4说明 Django 已经成功安装。方式二进入 Python 交互模式验证python然后在 Python 交互界面中输入import django print(django.get_version())如果正常输出版本号说明 Django 已经被正确导入。这种方式能确认 Django 在当前的 Python 解释器环境下可用避免出现 pip 安装到了全局环境但虚拟环境引用不到的情况。3.3 安装过程常见报错问题现象常见原因解决思路pip 提示No matching distribution found网络无法访问 PyPI 或 Python 版本过低切换国内镜像源或升级 Python 版本提示Django requires Python ...Python 版本与 Django 版本不匹配升级 Python或降低 Django 版本安装成功后 import 失败没有激活虚拟环境检查命令行前缀是否包含(venv)pip命令找不到Python 环境变量未配置重新安装 Python 时勾选 Add to PATH4. 创建第一个 Django 项目安装成功后我们就要开始创建项目了。这里需要先区分两个概念项目project和应用app。在 Django 中项目是整个网站的配置和入口而应用是项目下的功能模块。一个项目可以包含多个应用比如一个电商项目下可以包含用户应用、商品应用、订单应用。这个关系我们用下面的表格来简单说明概念作用数量Project 项目存储全局配置、路由、设置一个项目App 应用实现具体的业务功能模块一个项目可以有很多个4.1 使用 django-admin 创建项目我们首先创建一个项目目录然后在该目录下创建 Django 项目。# 创建一个存放项目的文件夹 mkdir myblog cd myblog激活虚拟环境后创建项目django-admin startproject config .这里有两个细节需要重点解释django-admin startproject configconfig是项目配置目录的名称。有些教程会用项目名作为配置目录名例如startproject myblog这会生成一个myblog的内部配置文件夹容易和项目根目录混淆。我们用config来命名语义更加清晰。末尾的点号.表示在当前目录下生成项目文件而不是再多套一层目录。加上点号后manage.py文件会直接出现在当前目录里项目结构更加扁平。4.2 项目结构详解执行完命令后你的项目目录应该是这样的myblog/ ├── manage.py └── config/ ├── __init__.py ├── settings.py ├── urls.py ├── asgi.py └── wsgi.py我们逐个来理解这些文件manage.pyDjango 的命令行管理工具。以后执行启动服务、创建应用、执行数据库迁移等操作时基本都要通过它来完成。config/__init__.py一个空文件告诉 Python 这个目录是一个 Python 包。config/settings.py项目的核心配置文件包括数据库配置、应用注册、模板路径、静态文件配置等后续开发中你会经常修改它。config/urls.py项目的 URL 声明入口处相当于你网站的“路由总表”。所有请求进来后都先到这里匹配再转发给对应的视图函数。config/asgi.py异步服务器网关接口配置用于部署异步服务时使用初学者可以先不管。config/wsgi.pyWeb 服务器网关接口配置当项目部署上线时Nginx Gunicorn 等服务器就是通过这个文件来启动你的 Django 应用。4.3 启动开发服务器项目创建好后我们就可以启动 Django 自带的开发服务器来测试一下。python manage.py runserver如果你没有指定端口它会默认运行在 8000 端口。首次运行你会看到类似下面的输出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. Django version 5.0.4, using settings config.settings Starting development server at http://127.0.0.1:8000/ Quit the server with CTRL-BREAK.这里提示有 18 个未应用的迁移这是 Django 自带的 admin、auth 等模块需要的数据库表目前先不用着急处理后续讲数据库迁移时再深入。4.4 浏览器访问测试打开浏览器在地址栏输入http://127.0.0.1:8000/如果你看到了一个类似火箭升空的画面并显示The install worked successfully! Congratulations!恭喜你你的 Django 项目已经成功运行了这个页面是 Django 的默认欢迎页它证明Python 环境一切正常Django 安装无误项目路由配置正确开发服务器正常工作4.5 修改端口与监听地址runserver命令还支持自定义端口和监听地址# 在 8080 端口启动 python manage.py runserver 8080 # 监听局域网所有地址方便手机或局域网内其他设备访问 python manage.py runserver 0.0.0.0:8000需要注意的是0.0.0.0表示监听本机所有网络接口。这样操作后同一局域网内的其他设备可以通过你电脑的 IP 地址访问这个 Django 项目。但出于安全考虑生产环境千万不要这样裸奔运行开发服务器生产环境应使用 Nginx Gunicorn 等专业部署方案。5. 创建第一个应用App项目已经跑通了但这只是一个空壳。接下来我们要在项目中创建一个应用实现一个最简单的页面。5.1 创建应用在项目根目录下执行python manage.py startapp blog执行命令后项目目录中会多出一个blog文件夹它的结构如下myblog/ ├── manage.py ├── config/ │ └── ... └── blog/ ├── __init__.py ├── admin.py ├── apps.py ├── models.py ├── tests.py ├── views.py └── migrations/ └── __init__.py这些文件的分工也很明确views.py视图文件负责处理业务逻辑。你写的函数或类大部分都在这里。models.py模型文件用来定义数据库表结构。admin.py后台管理配置文件将模型注册到 Django Admin。tests.py测试文件这是我们这篇文章后面的重点。apps.py应用配置信息。migrations/数据库迁移记录目录记录模型的每次变更。5.2 注册应用应用创建完成后需要告诉 Django 项目这个应用已经存在了。打开config/settings.py找到INSTALLED_APPS这一项INSTALLED_APPS [ django.contrib.admin, django.contrib.auth, django.contrib.contenttypes, django.contrib.sessions, django.contrib.messages, django.contrib.staticfiles, blog, # 新增这一行 ]这个小步骤很容易被初学者忽略。如果不注册应用Django 不会加载该应用下的模型和迁移文件后续很多操作都会报错。5.3 编写一个最简单的视图打开blog/views.py把默认内容替换成下面这个函数from django.http import HttpResponse def index(request): return HttpResponse(你好Django我的第一个页面。)这个视图函数接收一个request参数它包含了客户端的所有请求信息然后返回一个 HTTP 响应内容就是我们写的字符串。5.4 配置 URL 路由视图函数写好了但用户怎么访问到它呢这就要靠 URL 路由。首先在blog应用目录下新建一个urls.py文件写入以下内容from django.urls import path from . import views urlpatterns [ path(, views.index, nameindex), ]这里定义了一个空路径规则也就是当用户访问http://127.0.0.1:8000/时Django 会调用views.index视图函数。然后我们需要修改项目的config/urls.py把应用的 urls 文件包含进来from django.contrib import admin from django.urls import include, path urlpatterns [ path(admin/, admin.site.urls), path(, include(blog.urls)), ]这里用到了include()函数它的作用是把某个应用下的urls.py引入到项目总路由中。这样做的目的是当应用变得越来越多时每个应用可以独立管理自己的 URL 路由避免把所有的路由都堆在项目级urls.py中。5.5 验证页面效果保存所有文件后开发服务器通常会自动重启因为 Django 自带 auto-reload 功能。如果没有自动重启就手动按CtrlC停止服务然后重新运行python manage.py runserver再次访问http://127.0.0.1:8000/你应该看到页面上显示你好Django我的第一个页面。到这里你已经完成了第一个 Django 页面的开发流程创建项目 - 创建应用 - 注册应用 - 编写视图 - 配置路由 - 访问验证。这个流程就是以后所有 Django 项目开发的基础骨架建议反复练习直到完全熟练。6. Django 自带测试框架跑通第一个测试用例很多 Python 开发者在日常工作中容易忽略测试环节。但 Django 非常鼓励测试驱动开发它自带了一套完整的测试框架你不必安装额外的测试工具就能开始写测试。6.1 Django 测试框架的作用Django 的测试框架基于 Python 标准库的unittest模块。它的核心优势在于自动创建测试数据库测试运行时Django 会创建一个独立的测试数据库测试结束后自动销毁不影响你开发库中的数据。模拟请求环境Django 提供了Client类可以模拟浏览器向视图发送请求从而验证视图的返回结果。与模型紧密结合测试中可以方便地创建、查询、删除数据库记录验证业务逻辑是否正确。6.2 编写第一个测试用例打开blog/tests.py输入以下内容from django.test import TestCase from django.urls import reverse class BlogViewTests(TestCase): def test_index_view_returns_success(self): 测试首页视图能否正常返回 200 状态码 response self.client.get(reverse(index)) self.assertEqual(response.status_code, 200) def test_index_view_contains_expected_content(self): 测试首页响应内容是否包含预期文字 response self.client.get(reverse(index)) self.assertContains(response, 你好Django)这段测试代码做了三件事通过reverse(index)根据 URL 名称解析出真实的 URL 路径。使用self.client.get()模拟浏览器发出 GET 请求。断言响应状态码是否等于 200以及响应内容是否包含预期文字。6.3 运行测试在项目根目录下执行python manage.py test blog如果一切顺利你会看到类似下面的输出Creating test database for alias default... System check identified no issues (0 silenced). .. ---------------------------------------------------------------------- Ran 2 tests in 0.012s OK Destroying test database for alias default...看到OK说明两个测试全部通过。如果某一个断言失败测试输出中会详细显示预期值和实际值的差异帮助你快速定位问题所在。6.4 为什么要“先写测试再写功能”可能有人会觉得我们这页面这么简单看一眼浏览器就知道有没有问题为什么还要写测试这种想法在项目规模小的时候也许没问题但当项目发展到几十个页面、几十张数据表时手动测试的成本会越来越高。一个页面修改了数据库字段可能导致另一个页面的数据展示出错而你在浏览器上不一定能立刻发现。测试用例可以在几十秒内跑完全部核心逻辑把所有回归问题暴露出来。从工程实践的角度来说测试是保障代码质量的底线。后续系列文章中我们会在模型和视图的逻辑越来越复杂时继续补充测试用例的写法。7. 常见问题与排查思路不管前面的步骤写得多么详细实际动手时总会出现各种意外。作为初学阶段最常遇到的排错场景我按问题现象整理了下面这个排查表格也会补充一些关键步骤的说明以便大家更快定位问题。问题现象常见原因解决思路浏览器无法访问 127.0.0.1:8000开发服务器未启动确认终端是否显示Starting development server浏览器提示页面无法运行防火墙拦截检查系统防火墙是否放行 8000 端口修改代码后页面无变化开发服务器未自动重启手动 CtrlC 停止后重新运行ModuleNotFoundError: No module named blog应用未注册到 settings.py检查 INSTALLED_APPS 是否包含blog运行测试时提示数据库错误数据库迁移未执行执行python manage.py migrateTemplateDoesNotExist模板文件路径配置错误检查 settings.py 中的 TEMPLATES 配置django-admin不是内部或外部命令虚拟环境未激活重新激活虚拟环境或使用python -m django在实际项目中查询“Django执行查询-删除对象”等操作时如果操作不当导致数据异常也要第一时间检查事务提交情况和 WHERE 条件是否完整。后续系列文章中我会单独用一篇文章讲解 ORM 查询与数据删除的安全实践。7.1 排查思路从终端日志入手遇到问题不要慌首先要看运行 Django 的终端窗口输出了什么。比如如果页面访问报 404终端会显示Not Found: /xxx说明路由没匹配上。如果代码有语法错误终端会直接打印出错的代码行和报错信息。如果数据库出问题终端会打印数据库相关的异常堆栈。把这些报错信息复制到搜索引擎或 CSDN 搜索往往能很快找到解决方案。但要注意报错信息中经常会包含你项目的绝对路径搜索时最好把路径部分替换掉以免被别人看到不必要的信息。8. 最佳实践与工程建议环境搭建虽然只是一个起步动作但从这个阶段开始养成好的习惯会在后续的学习和工作中让你少踩很多坑。8.1 把虚拟环境排除在 Git 仓库之外如果你使用 Git 进行版本管理一定要在项目根目录创建.gitignore文件并把虚拟环境目录、数据库文件、本地配置等排除在外venv/ *.pyc __pycache__/ db.sqlite3 .env .mypy_cache/这样做的原因很简单虚拟环境是本地环境特有的其他开发者拿到项目代码后应该通过requirements.txt重新安装依赖而不是直接复用你的虚拟环境。8.2 锁定项目依赖版本在项目开发过程中把当前依赖的包版本记录下来方便后续重新部署。pip freeze requirements.txt后续别人拿到你的项目代码后直接执行pip install -r requirements.txt就能快速还原出一模一样的开发环境。8.3 数据库变更前先备份后续讲到模型操作时涉及数据库表的创建、修改、删除一定记住这个原则在测试环境验证提前备份谨慎执行。特别是删除操作DELETE和DROP是不可逆的务必在事务中操作并且先确认WHERE条件精确无误。8.4 不要在项目代码中硬编码敏感信息Django 的settings.py中默认生成的SECRET_KEY是敏感信息。在实际项目中我们应该通过环境变量或配置文件来管理密钥、数据库密码等敏感数据而不是把这些信息直接提交到 Git 仓库。例如import os SECRET_KEY os.environ.get(DJANGO_SECRET_KEY, unsafe-default-key)这样既能保证项目在本地能跑又能避免敏感信息泄露。8.5 合理使用 Django 内置的测试工具Django 自带测试框架已经覆盖了绝大部分场景不需要过早引入 pytest、selenium 等重量级工具。先把官方测试框架用熟练理解断言、测试客户端、测试数据库的机制再根据项目需要引入更高级的测试工具。9. 总结与下一步学习路线这篇文章我们从零开始完成了 Django 的安装、项目创建、应用创建、视图编写、URL 配置和自动化测试。核心操作流程可以用下面这张流程表完整概括阶段核心命令 / 操作验证方式环境准备python -m venv venv激活虚拟环境终端出现 venv 前缀安装 Djangopip install djangopython -m django --version创建项目django-admin startproject config .python manage.py runserver创建应用python manage.py startapp blog目录中出现 blog 文件夹注册应用编辑settings.py的 INSTALLED_APPS访问页面不报 ModuleNotFoundError编写视图编辑blog/views.py页面显示自定义内容配置路由编辑项目的 urls.py 和应用的 urls.py访问/能看到页面自动化测试python manage.py test blog输出 OK接下来可以继续学习的内容包括Django Admin 后台的使用与管理数据库模型Model的定义与查询模板系统Template与动态页面渲染表单处理与数据校验Django 中间件与信号机制用户认证与权限管理Django REST Framework 构建 API 接口如果你在安装或测试过程中遇到了本文没有覆盖的报错欢迎在评论区留言把完整的报错信息贴出来我看到了会及时回复。如果你的环境变量配置路径比较特殊或者需要跑在 Linux 服务器上进行部署后续我也会专门讲一讲飞牛 NAS 或其他服务器环境中搭建 Django 网站的高效方式。动手试一试建议你现在就打开终端按文章中的步骤亲手创建一个 Django 项目把第一个测试用例跑通。只有真正亲手操作一遍才能把安装过程中的各种细节内化为自己的经验。下一篇教程中我们将深入讲解 Django 的模型系统与数据库操作帮大家把数据持久化的核心知识补上。如果这篇文章对你有帮助欢迎点赞、收藏、转发让更多正在学习 Django 的开发者看到。我们下篇见。
