1. Django 是什么为什么入门要先学安装与测试1.1 Django 能解决什么问题Django 是一个基于 Python 的免费开源 Web 框架最初由 Lawrence Journal-World 的开发者们在 2003 年到 2005 年之间开发目的是让团队能在极短时间内完成新闻类网站的迭代。2005 年 7 月Django 以 BSD 许可证对外发布从此成为 Python 生态中最成熟的 Web 框架之一。从使用体验上讲Django 最核心的特点是“开箱即用”。开发者拿到一个全新的 Django 项目不需要自己去选配 ORM、模板引擎、表单处理、后台管理、会话管理、CSRF 防护等模块因为框架已经把这一整套常用组件整合好了。对比 Flask 这类微框架Django 更强调约定优于配置它默认提供一个清晰的项目结构让团队协作时有统一的规范可循。具体来说Django 解决了 Web 开发中常见的几个重复性问题数据库操作Django 内置 ORM开发者可以用 Python 代码操作数据库不需要手动拼接 SQL 语句。后台管理Django Admin 会自动为模型生成管理界面很适合内容管理和内部系统。表单处理Django Form 负责表单渲染、校验和错误提示。用户认证框架内置用户系统、权限分组和会话管理。安全性Django 自带 CSRF 防护、XSS 防护、SQL 注入防护等基础安全机制。1.2 为什么要从安装与测试开始在一次技术交流中不少初学者问我“Django 应该怎么学”我的建议永远是不要一上来就去研究复杂的模型关系或者中间件机制先把环境跑通、把开发服务器跑起来、把第一个最小项目跑起来再逐步深入。原因很简单如果环境都没装好后续学路由、模型、模板都会处处报错而且很难判断错误来自代码还是环境。安装与测试是 Django 学习链条中成本最低、收益最直接的一环。你只需要完成几个命令就能看到真实的页面在浏览器中打开这种正反馈对学习很有帮助。另一方面“测试”不只是指运行开发服务器后看一眼页面是否正常还包括使用 Django 自带的测试框架编写自动化测试用例。从第一天开始就养成写测试的意识后面写业务代码时会轻松很多。1.3 本文学习目标本文是 Django 快速入门系列的第一篇内容定位为“从零到第一个能跑通的项目”完成后你会掌握以下能力在本地环境中安装 Python 和 Django。创建虚拟环境并理解它的作用。使用django-admin命令创建项目。使用manage.py启动开发服务器。创建 Django 应用并编写一个简单的视图。使用 Django 自带的测试框架执行自动化测试。遇到常见安装和启动问题时具备独立排查能力。整个流程不涉及复杂的业务逻辑但每一步都是后续开发的地基值得认真消化。2. 环境准备Python 与虚拟环境2.1 检查 Python 版本Django 是 Python 的第三方库因此在安装 Django 之前必须先确保本机有可用的 Python 环境。 Django 不同版本对 Python 版本有不同要求例如 Django 4.2 LTS 支持 Python 3.8 到 3.12Django 5.0 支持 Python 3.10 以上。本文示例以当前主流的 Django 4.x 为参考如果后续版本有变化请以实际情况为准。打开命令行工具执行下面的命令检查 Python 版本python --version在 Linux 或 macOS 环境中如果系统里同时存在 Python 2 和 Python 3可能需要使用具体版本命令python3 --version这里的输出类似Python 3.10.12如果提示“python 不是内部或外部命令”或者“command not found”说明 Python 还没有安装或者没有加入系统的 PATH 环境变量。这时候需要先到 Python 官网下载对应操作系统的安装包安装时务必勾选“Add Python to PATH”选项否则后续命令可能无法执行。2.2 创建并激活虚拟环境很多初学者在安装 Django 时习惯直接执行pip install django这在个人电脑上一般能成功但存在隐患不同项目可能依赖不同版本的 Django如果全部安装到系统全局环境后面很容易出现版本冲突。虚拟环境可以理解成“项目专属的 Python 空间”。每个项目可以有自己独立的第三方库互不干扰。在实际开发和部署中虚拟环境是标准做法。在项目目录中创建虚拟环境的命令如下python -m venv venvvenv是 Python 3 自带的虚拟环境模块不需要额外安装。执行完成后当前目录下会生成一个名为venv的文件夹里面保存着这个虚拟环境的 Python 解释器和库目录。激活虚拟环境的方式根据操作系统有所不同。Windows 下的激活命令venv\Scripts\activateLinux 或 macOS 下的激活命令source venv/bin/activate激活成功后命令行提示符前面会出现(venv)标记例如(venv) C:\Users\user\projects\myblog以后执行pip install安装的包都会装进这个虚拟环境不会污染系统全局 Python。2.3 pip 源配置说明pip是 Python 官方的包管理工具通常安装 Python 后会自动带上。执行下面的命令可以检查 pip 版本pip --version在国内网络环境下直接使用官方源安装 Django 有时速度很慢甚至出现超时。此时可以将 pip 源切换为国内镜像源例如清华源、阿里源、豆瓣源等。以临时指定源为例pip install django -i https://pypi.tuna.tsinghua.edu.cn/simple如果想长期使用国内镜像源可以修改 pip 配置文件。Windows 下配置文件路径通常是%APPDATA%\pip\pip.iniLinux 或 macOS 下通常是~/.pip/pip.conf或~/.config/pip/pip.conf。配置内容如下[global] index-url https://pypi.tuna.tsinghua.edu.cn/simple trusted-host pypi.tuna.tsinghua.edu.cn需要说明的是镜像源的内容会实时同步 PyPI 官方仓库版本一般不会有滞后问题。但如果公司内部有私有 pip 源建议优先使用公司源。3. Django 安装与版本验证3.1 使用 pip 安装 Django确保虚拟环境已激活然后执行安装命令pip install django如果不指定版本pip 会默认安装当前最新的稳定版。如果你希望安装指定版本可以使用指定例如pip install django4.2.11在写项目时我建议优先安装 LTS 长期支持版本。LTS 版本维护周期更长社区资料更丰富遇到兼容性问题也更容易在搜索引擎中找到解决方案。至于最新版本虽然能尝鲜使用新特性但版本升级带来的兼容性风险需要自己承担。安装过程中pip 会自动下载 Django 及其依赖项。由于 Django 的核心依赖比较少所以安装速度通常较快。安装完成后最好截留一段等待时间不用急着做下一步先确认安装是否真的成功。3.2 验证安装结果验证 Django 是否安装成功最简单的办法是在命令行中进入 Python 交互环境尝试导入 Django 并输出版本号python进入 Python 交互环境后输入import django print(django.get_version())如果输出类似4.2.11的内容说明 Django 已经正确安装。退出 Python 交互环境可以按Ctrl ZWindows或Ctrl DLinux/macOS。除了在 Python 中验证还可以用命令行直接查看版本python -m django --version另外pip show命令能查看 Django 的详细信息包括安装路径和依赖关系pip show django输出内容大概如下Name: Django Version: 4.2.11 Summary: A high-level Python web framework that encourages rapid development and clean, pragmatic design. Location: /path/to/venv/lib/python3.10/site-packages看到Location指向虚拟环境下的 site-packages 路径说明 Django 确实安装在虚拟环境中而不是系统全局环境。3.3 安装内容详解很多初学者只知道 Django 是一个框架但并不知道 pip install 之后到底装了哪些东西。简单拆解一下安装 Django 后会得到django-admin命令行工具用于创建项目和管理项目。djangoPython 包包含框架的源码、模板引擎、ORM、中间件等模块。一系列内置应用比如auth、admin、sessions、staticfiles等。默认的模板和静态文件管理机制。django-admin是全局可执行文件但在虚拟环境中它只对当前虚拟环境生效。如果你在项目开发过程中发现命令找不到多半是因为没有激活虚拟环境或者 Django 安装到了别的 Python 环境中。4. 创建第一个 Django 项目4.1 使用 django-admin 创建项目安装完成后进入准备存放项目的目录比如~/projects或D:\projects执行以下命令django-admin startproject mysite这里的mysite是项目名。Django 会创建一个名为mysite的文件夹里面自动生成一套可运行的项目骨架。为了方便后续跟读建议项目名统一使用小写字母和下划线不要使用my-site或my site这样的命名因为 Python 包名不合法。命令执行后项目目录结构如下mysite/ manage.py mysite/ __init__.py settings.py urls.py asgi.py wsgi.py最外层mysite是项目的容器目录里面的mysite是项目配置包。每个文件的作用如下manage.py项目管理和运行入口后续大量命令都是通过它执行。__init__.py标识当前目录是一个 Python 包。settings.py项目配置文件数据库、应用、模板、静态文件都在这里配置。urls.pyURL 路由分发配置。asgi.py异步服务器网关接口入口用于部署兼容 ASGI 的服务器。wsgi.pyWSGI 入口用于传统部署方式。4.2 项目目录结构说明新手看到这一堆文件可能会觉得复杂但不要被吓到。现阶段只需要关注manage.py和settings.py其他文件后续用到时再深入。manage.py提供的常用命令包括python manage.py runserver启动开发服务器。python manage.py startapp创建新应用。python manage.py makemigrations根据模型变化生成迁移文件。python manage.py migrate执行数据库迁移。python manage.py test运行测试。python manage.py createsuperuser创建管理员账号。settings.py是项目的大脑。它控制着 DEBUG 模式、允许访问的主机列表、数据库连接、应用注册列表、语言时区等。初学阶段不建议大改但当浏览器访问出现 “DisallowedHost” 错误时就需要修改ALLOWED_HOSTS配置。4.3 配置 settings.py 基础项刚创建的项目settings.py中有几个开关值得提前了解# 项目根目录的 BASE_DIR BASE_DIR Path(__file__).resolve().parent.parent # 调试模式开关 DEBUG True # 允许访问的主机列表 ALLOWED_HOSTS [] # 应用注册列表 INSTALLED_APPS [ django.contrib.admin, django.contrib.auth, django.contrib.contenttypes, django.contrib.sessions, django.contrib.messages, django.contrib.staticfiles, ]DEBUG True表示当前处于开发模式Django 会输出详细错误页静态文件也能自动提供。生产环境中必须设置为False否则会暴露代码路径和敏感信息。ALLOWED_HOSTS空列表表示只允许本机访问如果需要在局域网中让其他机器访问开发服务器可以写成[*]或者具体的 IP 地址。语言和时区配置在文件末尾附近建议改成中国用户习惯的配置LANGUAGE_CODE zh-hans TIME_ZONE Asia/Shanghai改完之后Django 后台界面会显示中文时间也会按北京时间处理。5. 启动开发服务器并进行访问测试5.1 启动 runserver切换到项目根目录即包含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. Starting development server at http://127.0.0.1:8000/ Quit the server with CONTROL-C.注意Django 开发服务器默认监听127.0.0.1:8000这表示只能本机访问。如果想指定端口可以追加参数python manage.py runserver 8080等待几秒后项目就正式跑起来了。开发服务器会自动监听代码文件变化修改 Python 文件后服务会自动重载不需要手动重启。5.2 浏览器访问与预期结果在浏览器地址栏输入http://127.0.0.1:8000/你会看到 Django 的默认欢迎页页面背景是火箭发射的插画标题一般是 “The install worked successfully! Congratulations!”这个页面说明项目已经成功运行同时也提供了关键提示如果你打算使用数据库需要执行python manage.py migrate。默认情况下Django 使用 SQLite 数据库这是一个轻量级的文件型数据库不需要额外安装数据库服务非常适合学习和本地开发。在浏览器访问页面时留意控制台输出的日志[27/Feb/2025 10:22:31] GET / HTTP/1.1 200 10835其中200表示 HTTP 状态码说明请求成功。如果后续看到404或500就需要根据日志排查页面路径或代码错误。5.3 开发服务器的行为特点开发服务器虽然方便但它不是为生产环境设计的。在生产部署时通常使用 Gunicorn、uWSGI 等 WSGI 服务器或者搭配 Nginx 做反向代理。开发服务器不支持高并发性能也远不如生产服务器因此不要把它当作真正的线上服务来用。另一个特性是自动重载。当你修改了 Python 代码开发服务器会检测到文件变化并自动重启。但有一些文件变化可能不会被正确检测比如添加新文件、修改系统配置等此时可以手动按Ctrl C停止服务再重新执行runserver。还有一个细节值得注意如果在运行过程中遇到 “port already in use” 错误说明 8000 端口被其他程序占用。解决办法是指定其他端口或找到占用进程并关闭它。6. 编写第一个 Django 应用与测试用例6.1 创建应用 appDjango 的项目和概念可以这样理解项目是整个网站的配置集合应用则是功能模块。一个项目可以包含多个应用例如一个博客系统可以有文章应用、用户应用、评论应用。使用 startapp 命令创建应用python manage.py startapp blog执行后项目目录会新增一个blog文件夹结构如下blog/ __init__.py admin.py apps.py migrations/ __init__.py models.py tests.py views.py其中views.py是视图逻辑所在models.py用来定义数据模型tests.py用来编写自动化测试用例。不过应用创建后还需要在settings.py的INSTALLED_APPS中注册Django 才会把它纳入项目。在INSTALLED_APPS列表末尾添加INSTALLED_APPS [ # 默认应用省略 blog, ]注册应用之后Django 才会扫描该应用下的模型、后台配置、迁移文件等。6.2 编写视图与 URL 映射打开blog/views.py编写一个最简单的视图函数from django.http import HttpResponse def index(request): return HttpResponse(Hello Django, this is my first app.)视图函数接收一个request对象返回一个HttpResponse对象。当用户访问对应 URL 时Django 会调用这个视图函数把返回的内容作为网页响应发送给浏览器。接下来在blog应用目录下创建一个urls.py文件用来定义应用内部的 URL 路由from django.urls import path from . import views urlpatterns [ path(, views.index, nameindex), ]然后在项目主目录的mysite/urls.py中把应用的路由包含进来。修改后的内容如下from django.contrib import admin from django.urls import include, path urlpatterns [ path(admin/, admin.site.urls), path(blog/, include(blog.urls)), ]include函数的作用是把blog应用的 URL 配置挂载到/blog/路径下。这样访问http://127.0.0.1:8000/blog/就会执行blog应用中的index视图。保存文件后开发服务器会自动重载。重新在浏览器访问http://127.0.0.1:8000/blog/页面会显示Hello Django, this is my first app.至此你已经通过 Django 完成了从请求到响应的完整链路。6.3 使用 Django 自带测试框架运行测试Django 自带测试框架基于 Python 标准库的unittest。编写测试可以让代码在修改后快速回归避免改一个功能弄坏另一个功能。打开blog/tests.py修改为以下内容from django.test import SimpleTestCase from django.urls import reverse class BlogViewTests(SimpleTestCase): def test_index_view(self): response self.client.get(/blog/) self.assertEqual(response.status_code, 200) self.assertContains(response, Hello Django) def test_index_view_by_name(self): response self.client.get(reverse(index)) self.assertEqual(response.status_code, 200)这里用到了SimpleTestCase适用于不需要数据库的视图测试。self.client是 Django 提供的测试客户端它可以模拟浏览器发起 HTTP 请求不需要真正启动开发服务器。第一个测试用例访问/blog/路径断言响应状态码为 200并且页面内容包含 “Hello Django”。第二个测试用例通过 URL name 反向解析得到路径再发起请求。在项目根目录执行测试python manage.py test blog预期输出Found 2 test(s). Creating test database for alias default... System check identified no issues (0 silenced). .. ---------------------------------------------------------------------- Ran 2 tests in 0.012s OK看到OK说明两个测试用例都通过了。这里有个细节如果测试过程中涉及模型操作Django 会创建一个临时测试数据库测试结束后自动销毁不会污染开发数据。这是非常重要的一项安全设计。如果修改views.py中的返回内容比如把文字改成 “Hi Django”再次运行测试就会失败提示找不到 “Hello Django”。这个失败能让你感受到测试的意义它用自动化方式代替人工回归检查。7. 常见问题与排查思路7.1 表格速查问题现象常见原因解决思路pip 安装速度慢或超时官方源网络不稳定切换国内镜像源提示 command not found: django-admin虚拟环境未激活或未安装 Django激活虚拟环境后重新安装访问页面出现 DisallowedHostALLOWED_HOSTS 未配置该域名或 IP在 settings.py 中允许对应主机runserver 启动报端口占用8000 端口被其他程序占用换端口或结束占用进程浏览器页面无法访问开发服务器未启动或端口不对确认启动日志和访问地址修改代码后页面没变化自动重载未生效手动重启开发服务器执行 migrate 时报错数据库配置或迁移文件异常检查数据库配置并查看完整报错7.2 深入排查方法遇到问题不要急着乱试命令先用最笨但最有效的方法看完整报错信息。Django 的报错页面和命令行输出通常已经给出了明确的线索例如缺少哪个模块、哪一行代码出错、哪个配置项不合法。以 “DisallowedHost” 为例报错页面会显示当前访问的 Host 值。如果你需要局域网内其他设备访问开发服务器需要把对应 IP 加入ALLOWED_HOSTS例如ALLOWED_HOSTS [192.168.1.100, localhost, 127.0.0.1]如果只是想快速测试可以临时设置为[*]但生产环境不要这样做否则可能被恶意请求攻击。再比如如果启动时看到迁移警告虽然不阻止服务器运行但建议尽早执行python manage.py migrate这个命令会根据 Django 内置应用和自定义应用生成的数据表结构在 SQLite 中创建对应的表。如果不执行迁移后续访问后台管理页面时可能会因为数据表缺失而报错。7.3 版本兼容性问题Django 版本与 Python 版本不匹配是安装阶段最常见的问题之一。在安装前先确认本机 Python 版本再查询对应 Django 版本支持的 Python 范围。如果你在pip install django时看到类似 “Django requires Python 3.10” 的错误说明当前 Python 版本过低。这时候有两个选择升级 Python 到兼容版本或者安装一个支持当前 Python 版本的旧版 Django。使用旧版 Django 的命令pip install django3.2.25不过旧版 Django 可能不再维护安全补丁长期来看还是建议升级 Python 环境。8. 最佳实践与工程建议8.1 使用虚拟环境并固定依赖版本在真实项目中“环境不一致”是协作开发中很大的痛点。为了让团队成员和服务器复现相同的运行环境最好在项目中维护一份依赖清单。生成依赖清单的命令pip freeze requirements.txtrequirements.txt的内容类似Django4.2.11当其他开发者拿到项目后执行pip install -r requirements.txt就能安装完全相同的依赖版本。这样做的好处是避免因为小版本差异导致莫名其妙的 bug。8.2 配置管理的安全意识Django 项目中的settings.py包含数据库密码、密钥等敏感信息。在实际项目中不要把密钥直接硬编码到代码仓库尤其是使用 Git 管理时。推荐的做法是把敏感配置放在环境变量中例如import os SECRET_KEY os.environ.get(DJANGO_SECRET_KEY, fallback-key) DEBUG os.environ.get(DJANGO_DEBUG, False) True这里只用show-env和os.environ做示例目的是告诉你配置和代码分离的思路。具体配置方式可以根据团队规范灵活调整。8.3 测试驱动开发的起步思路本文演示的测试用例虽然简单但它代表了一种开发习惯先写测试再写功能。把期望的行为用测试表达出来然后实现代码让测试通过。这样做能提升代码质量因为你在动手写代码之前已经想清楚了“要做什么”。对于学完本文的读者可以先从两个方向继续练习为每个新视图补充测试覆盖正常访问和错误路径。为模型添加测试验证数据创建和查询行为是否符合预期。8.4 文件与命名规范Django 项目中应用名应使用复数或单数名词例如blog、articles、users不要用myapp1这种没有语义的名字。视图函数名要能表达功能比如article_detail、user_profile。 URL 路径设计保持小写单词之间用连字符或下划线但要保持一致。另外每个应用内部可以继续按功能拆分子目录例如blog/views/目录下放置多个视图模块。不过这个属于进阶组织方式入门阶段保持简单即可。9. 总结与下一步学习方向到这一步你已经完成了 Django 从安装到运行、从创建应用到编写测试的完整闭环。回顾一下我们做了以下几件事检查 Python 环境创建虚拟环境使用 pip 安装 Django验证安装结果创建项目和应用启动开发服务器编写视图与 URL 映射并使用 Django 自带测试框架执行了自动化测试。有一个细节想再次强调不要跳过虚拟环境。它能避免不同项目之间的依赖冲突是保护开发环境的基本手段。接下来可以继续学习的方向包括Django 模型与数据库迁移学习如何定义数据表、增加字段、查询数据。Django Admin 后台利用内置后台管理系统管理业务数据。Django 模板编写 HTML 页面在页面中展示动态数据。Django 表单处理用户输入、数据校验和错误提示。用户认证系统注册、登录、权限控制。本文对应的项目和代码都比较简单建议你亲手敲一遍而不是直接复制运行。自己在命令中遇到报错、自己排查出来这个过程中学到的东西比看十遍教程都扎实。如果本文对你有帮助可以收藏备用后续系列文章会继续深入 Django 的模型、视图、模板和部署我们一起把 Django 主线走完。