安装 Django 看起来只是执行一条pip install django命令但实际进入项目时很多人会卡在 Python 版本选择、虚拟环境创建、Django 项目目录结构理解、测试服务器启动失败这几个环节。这篇入门文章以“安装并跑通最小 Django 项目、验证测试链路”为主线从框架概念讲起完整覆盖环境准备、安装验证、项目创建、app 注册、自动化测试运行最后给出常见报错排查路径和生产环境注意事项。读者只需要有基础的 Python 语法知识不需要提前掌握 Web 框架概念。1. 先理解 Django 是什么以及安装前需要确认什么Django 是一个用 Python 编写的开源 Web 框架采用 MTV 模式官方设计目标是帮助开发者快速构建数据库驱动、安全、可扩展的 Web 应用。它内置了 ORM、Admin 后台、表单处理、认证系统、模板引擎和测试工具很多功能不需要额外找第三方库。安装 Django 并不复杂但安装前有三个前置问题需要确认。第一个是 Python 版本Django 对 Python 版本有明确要求不同 Django 大版本支持的 Python 小版本范围不同混用会导致部分功能不可用或直接安装失败。第二个是包管理器Python 3.4 之后自带pip但不同操作系统、不同 Python 安装方式下pip指向的解释器可能不同这在多 Python 环境共存时尤其容易出错。第三个是虚拟环境虚拟环境可以把当前项目的依赖与系统级 Python 环境隔离避免不同项目依赖相同包的不同版本时互相覆盖。从学习路径看先安装 Django 并跑通测试服务器是理解 Django 项目结构、请求处理链路和配置文件作用的起点。这一篇不会深入 ORM、模板继承、Admin 定制等内容但会为后续学习打好目录和配置基础。2. 环境准备Python 版本、虚拟环境和 pip 检查2.1 确认 Python 版本Django 4.2 LTS 版本要求 Python 3.8 及以上Django 5.0 要求 Python 3.10 及以上Django 5.2 LTS 要求 Python 3.10 及以上。实际项目里优先选择 LTS 版本因为官方支持周期更长社区资料也更丰富。这里以 Django 5.2 LTS 作为示例但安装步骤在 Django 4.2 和 Django 5.x 上基本一致。先检查本机 Python 版本python --version python3 --version python3.12 --version不同操作系统执行命令时需要留意操作系统常见 Python 命令说明Windowspython安装 Python 时勾选 “Add Python to PATH” 后可直接使用macOSpython3系统自带的是 Python 3但版本可能较旧Linuxpython3多数发行版不提供python命令或python指向 Python 2如果本机没有 Python 3.10 以上版本需要先安装 Python。Windows 推荐从 Python 官网下载安装包安装时勾选 “Add Python to PATH”macOS 可以使用 Homebrew 安装Linux 使用发行版包管理器安装或源码编译。这里不建议使用系统自带的旧版本 Python因为 Django 新版本会使用较新的语言特性旧解释器无法运行。2.2 创建虚拟环境虚拟环境是安装 Django 前最值得养成的习惯。在项目目录中执行mkdir django-demo cd django-demo python -m venv venv执行后会在django-demo目录下生成venv文件夹里面包含独立 Python 解释器、pip和基础标准库副本。激活虚拟环境的方式因操作系统而异Windows PowerShell 或 CMDvenv\Scripts\activatemacOS 或 Linuxsource venv/bin/activate激活后命令行提示符前面会显示(venv)说明当前 shell 正在使用虚拟环境中的 Python。此时执行python和pip操作都只影响当前项目不会污染系统环境。注意虚拟环境激活只对当前终端窗口有效。关闭终端后再次进入项目需要重新激活。2.3 升级 pip虚拟环境自带一个基础版本 pip建议先升级到最新版本避免安装 Django 时因 pip 版本过低出现解析依赖失败或 SSL 报错。python -m pip install --upgrade pip执行完成后确认 pip 版本和对应的 Python 路径pip --version正常输出应包含venv目录路径例如pip 24.0 from /path/to/django-demo/venv/lib/python3.12/site-packages/pip (python 3.12)如果pip指向的不是虚拟环境路径说明激活失败或者当前使用的 pip 不属于虚拟环境。此时需要重新确认激活命令是否执行成功。3. 安装 Django 并验证安装结果3.1 使用 pip 安装 Django虚拟环境激活后执行安装命令pip install django默认会安装当前 PyPI 上稳定的最新版本。若希望安装指定版本可以使用版本限定pip install django5.2 pip install django4.2,5.1这里建议学习阶段安装最新 LTS 或当前稳定版。安装过程中 pip 会下载 Django 及其依赖输出进度条和成功信息。安装完成后可以通过三个命令验证python -m django --version django-admin --version python -c import django; print(django.get_version())python -m django --version是推荐方式因为它显式使用当前虚拟环境中的 Python 解释器执行 Django 模块可以避免系统存在多个 Django 版本时误判。django-admin是 Django 提供的命令行工具用于创建项目、创建 app、启动测试服务器等操作。3.2 确认安装文件位置如果安装过程没有报错但运行时提示找不到 Django可以检查安装路径pip show django输出会包含Location字段表示 Django 包被安装到了哪个目录。如果这个路径不在当前虚拟环境中说明安装时没有使用虚拟环境的 pip。安装验证环节常见三种情况验证命令正常结果异常结果处理方式python -m django --version输出版本号如 5.2No module named django确认虚拟环境已激活重新安装 Djangodjango-admin --version输出版本号提示命令不存在检查虚拟环境Scripts或bin目录是否在 PATH 中python -c import django; print(django.get_version())输出版本号导入错误确认当前 Python 解释器来自虚拟环境4. 创建 Django 项目并理解生成的文件4.1 使用 django-admin 创建项目安装验证通过后在虚拟环境激活状态下创建项目。Django 项目可以理解为“网站实例”它包含全局配置文件、URL 入口、WSGI/ASGI 接口和 app 管理入口。执行django-admin startproject config .注意命令末尾有一个.表示在当前目录下生成项目配置文件。如果不加点startproject会在当前目录下再创建一个与项目同名的子目录层次会多一层后续执行python manage.py时容易路径混淆。执行成功后当前目录结构如下django-demo/ ├── venv/ ├── config/ │ ├── __init__.py │ ├── asgi.py │ ├── settings.py │ ├── urls.py │ └── wsgi.py └── manage.py这里以config作为项目配置目录名实际项目可以使用项目名比如myproject。manage.py是 Django 提供的项目管理脚本后续执行的所有命令基本都依赖它。4.2 核心文件作用文件作用学习阶段的关注点manage.py命令行入口封装了django-admin的大部分功能运行服务器、迁移数据库、创建 app、执行测试都会用到config/settings.py项目全局配置包含 DEBUG、INSTALLED_APPS、DATABASES、TEMPLATES 等新创建的 app 需要注册到这里config/urls.pyURL 路由入口把请求地址映射到视图函数后续需要通过include引入 app 的 URLconfig/wsgi.pyWSGI 服务入口用于部署到传统 Web 服务器本地测试不直接使用生产部署时才需要config/asgi.pyASGI 服务入口用于支持异步功能的服务器生产部署时使用Django 4.x 之后默认生成4.3 验证项目能否启动创建项目后先不修改任何代码直接启动自带的开发测试服务器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) in your project (run manage.py migrate). Django version 5.2, using settings config.settings Starting development server at http://127.0.0.1:8000/ Quit the server with CONTROL-C.注意中间的提示You have 18 unapplied migration(s)。这是 Django 内置 app 需要初始化数据表第一次运行测试服务器不影响启动但后续使用 Admin 后台或内置用户系统时必须先执行迁移。5. 创建 Django app 并跑通最小请求链路5.1 app 与 project 的区别一个 Django 项目可以包含多个 app每个 app 负责一个独立业务模块比如用户管理、博客文章、订单系统。这种拆分方式是 Django 项目组织代码的核心思路。创建第一个 apppython manage.py startapp blog创建后会在项目根目录生成blog目录blog/ ├── __init__.py ├── admin.py ├── apps.py ├── migrations/ ├── models.py ├── tests.py └── views.py5.2 将 app 注册到 INSTALLED_APPS如果不注册 appDjango 虽然能启动但不会加载 app 中的模型、迁移、信号、模板等资源。打开config/settings.py找到INSTALLED_APPS列表把blog加进去INSTALLED_APPS [ django.contrib.admin, django.contrib.auth, django.contrib.contenttypes, django.contrib.sessions, django.contrib.messages, django.contrib.staticfiles, blog, ]注册后Django 的系统检查机制会识别到blog是一个已安装的 app。如果不注册直接访问该 app 下的视图路由虽然能匹配但涉及模型和模板的部分会报错。5.3 编写最小视图打开blog/views.py写入一个最简单的视图函数from django.http import HttpResponse def index(request): return HttpResponse(Hello, Django!)视图函数接收request对象返回HttpResponse对象。这里没有使用模板目的是先验证 URL 到视图的链路是否连通。5.4 配置 URL 路由在blog目录下新建urls.py文件from django.urls import path from . import views urlpatterns [ path(, views.index, nameindex), ]然后在config/urls.py中把 blog 的 URL 引入项目入口from django.contrib import admin from django.urls import include, path urlpatterns [ path(admin/, admin.site.urls), path(blog/, include(blog.urls)), ]这样配置后访问http://127.0.0.1:8000/blog/时会进入blog下的 URL 文件匹配到空字符串路径执行views.index。重启测试服务器python manage.py runserver浏览器访问http://127.0.0.1:8000/blog/页面显示Hello, Django!说明请求链路已经跑通。6. 使用 Django 自带测试框架验证功能6.1 Django 为什么内置测试工具很多开发者在学习 Django 时会把测试放在最后但 Django 社区推荐的做法是“先写测试或用测试驱动开发”。Django 自带的测试框架基于 Python 标准库unittest不需要额外安装第三方库支持创建测试数据库、模拟请求、断言响应状态码和内容。这一篇只做最简单的测试验证目的是确认测试命令可以正常执行为后续编写真正业务测试做准备。6.2 编写第一个测试用例打开blog/tests.py替换为以下内容from django.test import TestCase from .views import index class IndexViewTests(TestCase): def test_index_returns_hello_django(self): response self.client.get(/blog/) self.assertEqual(response.status_code, 200) self.assertContains(response, Hello, Django!)这里用到了两个核心工具self.clientDjango 测试客户端可以在不启动服务器的情况下模拟 GET、POST 请求。assertEqual和assertContains断言响应状态码和响应内容是否符合预期。6.3 运行测试并分析结果执行测试命令python manage.py test正常输出Found 1 test(s). Creating test database for alias default... System check identified no issues (0 silenced). . ---------------------------------------------------------------------- Ran 1 test in 0.012s OK Destroying test database alias default...测试框架自动创建了一个临时测试数据库测试结束后销毁不会污染开发数据库。如果要更详细查看测试执行过程可以在blog/tests.py中加一行打印信息或者使用--verbosity参数python manage.py test --verbosity 2如果修改过视图返回内容导致测试失败输出会显示断言错误和实际响应内容。这种反馈速度比手动刷新浏览器验证快很多。7. 数据库迁移让内置 app 的数据表可用7.1 为什么执行 migrate前面启动服务器时有一个提示要求执行迁移。迁移是把models.py中定义的模型映射到数据库表的过程。Django 默认使用 SQLite 数据库不需要额外安装数据库服务学习阶段非常方便。执行迁移python manage.py migrate输出会显示每个 app 应用迁移的记录例如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文件。这是 Django 生成的 SQLite 数据库文件。7.2 如何配置其他数据库SQLite 适合学习和原型开发生产环境通常使用 PostgreSQL 或 MySQL。在config/settings.py中修改DATABASES配置即可切换DATABASES { default: { ENGINE: django.db.backends.postgresql, NAME: myproject, USER: myprojectuser, PASSWORD: password, HOST: 127.0.0.1, PORT: 5432, } }需要注意迁移命令和数据库连接配置是绑定在一起的切换数据库后需要重新执行migrate生成对应数据库的表结构。8. 启动测试服务器时的疑难点排查测试服务器跑不起来、访问页面报错是入门阶段最消耗时间的部分。这里按照从现象到原因的排查顺序整理常见问题。8.1 端口被占用现象执行python manage.py runserver后提示类似Error: That port is already in use.原因8000 端口已经被其他进程占用。处理方式python manage.py runserver 8001指定其他端口启动。也可以查找占用进程后手动关闭Windows 使用netstat -ano配合任务管理器macOS 和 Linux 使用lsof -i :8000。8.2 找不到 manage.py 或模块配置错误现象执行python manage.py runserver提示No module named config原因当前工作目录不是项目根目录Python 无法导入config配置模块。处理方式是先使用ls或dir确认目录下是否有manage.py然后进入对应目录再执行。8.3 路由导入错误现象访问http://127.0.0.1:8000/blog/时提示ModuleNotFoundError: No module named blog原因app 没有创建成功或者目录名称写错。处理方式是检查blog目录是否存在并检查config/urls.py中的导入路径。8.4 页面显示 404现象访问http://127.0.0.1:8000/时出现 404。原因项目根路径没有配置任何视图Django 默认只配置了admin/路由。处理方式是在config/urls.py中增加根路径路由或者在浏览器访问已经配置的路径。8.5 系统检查不通过现象启动服务器时提示System check identified X issues。原因配置有问题可能是INSTALLED_APPS写错、URL 路径冲突等。处理方式是查看服务器输出的具体错误信息先按错误提示逐条修改。不要忽略这条提示某些错误会直接导致访问时抛异常。9. Django 入门阶段的高频错误和避免方法9.1 在虚拟环境外使用 pip 安装错误写法pip install django但当前没有激活虚拟环境或者激活后又换了一个终端窗口。原因系统全局环境安装了 Django当前项目无法保证使用正确版本。推荐做法每个项目都创建独立虚拟环境执行安装前先确认命令行提示符有(venv)前缀。9.2 把 app 创建在错误位置错误现象执行python manage.py startapp blog时不在项目根目录导致 app 被创建到其他目录manage.py无法识别。推荐做法始终在包含manage.py的目录下执行startapp。创建后检查目录结构是否符合预期。9.3 忘记注册 app错误现象模型、模板、测试都没有生效但 Django 没有立刻报错。原因Django 只会处理注册到INSTALLED_APPS中的 app。推荐做法创建 app 后立刻修改config/settings.py在INSTALLED_APPS列表末尾添加 app 名称。9.4 直接修改生成的文件后无法恢复错误现象修改settings.py后忘记备份改乱了无法恢复。推荐做法入门阶段对不认识的关键字先不要删除只做增量修改。比如注册 app、增加数据库配置时只添加新内容。10. 常见问题速查表问题可能原因检查方式处理建议安装 Django 时提示找不到版本Python 版本过低或 pip 源不可用python --version、python -m pip --version升级 Python 或使用国内 pip 镜像源启动服务器提示 No module named django虚拟环境未激活或 Django 装到了别处which python、python -m django --version重新激活虚拟环境后再安装修改代码后页面没变化服务器没有自动重载观察终端是否输出Reloading...按 CtrlC 停止然后重新启动服务器访问页面出现 500视图代码有异常查看终端完整报错栈修复代码后重新访问页面测试命令找不到测试用例测试方法没有以 test 开头检查tests.py中方法名测试方法名必须以test开头数据库迁移失败数据库配置错误或已有表结构冲突查看迁移错误日志确认数据库连接参数必要时重置测试库11. 学习环境与生产环境的差异项目学习环境生产环境运行方式runserver内嵌服务器Gunicorn Nginx或 uWSGI NginxDEBUG 配置保持DEBUG True方便调试必须设置为False否则会泄露配置和代码信息数据库SQLite 文件数据库PostgreSQL 或 MySQL 独立数据库服务静态文件Django 自带静态文件处理使用 Nginx 或 CDN 托管静态文件密钥管理直接写在settings.py通过环境变量或配置中心注入日志终端输出即可文件日志、日志轮转、集中日志平台测试本地执行manage.py testCI 流水线中自动执行包含回归和覆盖率检查迁移直接执行migrate先执行makemigrations审查再在发布窗口执行迁移生产环境还需要额外考虑的安全措施包括关闭 DEBUG、配置ALLOWED_HOSTS、设置安全响应头、限制访问权限、使用环境变量管理密钥和数据库连接串。12. Django 安装后的下一步练习建议这一篇完成了 Django 安装、项目创建、app 创建、测试服务器启动和基础测试验证下一步建议按以下路径继续实践使用python manage.py startapp创建第二个 app体会一个应用拆分成多个模块的意义。在blog/models.py定义一个数据模型执行makemigrations和migrate然后在 Django Admin 后台添加、修改数据。把views.py中的HttpResponse改成render返回模板理解模板目录配置。给blog增加表单提交体验 POST 请求和 CSRF 防护机制。为业务代码编写测试用例运行manage.py test把测试命令纳入日常开发流程。对于刚入门的学习者最值得养成的习惯有三个每次进入项目先激活虚拟环境修改配置后先运行python manage.py check做系统检查完成一个功能模块后立刻用测试框架验证而不是只靠浏览器手动访问。安装只是第一步真正理解 Django 的请求链路、配置加载过程和 app 组织方式才能在后边的学习中减少重复踩坑。