我们假定你已经阅读了​ 安装 Django。你能知道 Django 已被安装，且安装的是哪个版本，通过在命令提示行输入命令（由 $ 前缀）。

$ python -m django --version

如果这行命令输出了一个版本号，证明你已经安装了此版本的 Django；如果你得到的是一个“No module named django”的错误提示，则表明你还未安装。

本教程适用于 Django 5.1，支持 Python 3.10 及更高版本。如果 Django 版本不匹配，您可以使用本页面右下角的版本切换器查看适用于您 Django 版本的教程，或者将 Django 更新到最新版本。

创建项目

如果这是你第一次使用 Django 的话，你需要一些初始化设置。也就是说，你需要用一些自动生成的代码配置一个 Django Project—— 即一个 Django 项目实例需要的设置项集合，包括数据库配置、Django 配置和应用程序配置。

在命令行中，使用 cd 进入你希望存储代码的目录，并创建一个名为 djangotutorial 的新目录。（这个目录名称对 Django 来说并不重要，你可以将其重命名为任何你喜欢的名称。 

$ mkdir djangotutorial

  然后，运行以下命令来引导一个新的 Django 项目：

$ django-admin startproject mysite djangotutorial

这将在 djangotutorial 目录内创建一个名为 mysite 的项目。 

 你得避免使用 Python 或 Django 的内部保留字来命名你的项目。具体地说，你得避免使用像 django (会和 Django 自己产生冲突)或 test (会和 Python 的内置组件产生冲突)这样的名字。

让我们看看 startproject创建了些什么：

djangotutorial/
    manage.py
    mysite/
        __init__.py
        settings.py
        urls.py
        asgi.py
        wsgi.py

这些目录和文件的用处是：

• manage.py: 一个让你用各种方式管理 Django 项目的命令行工具。 

• mysite/: 一个目录，它是你项目的实际 Python 包。它的名称是你需要用来导入其中任何内容的 Python 包名称（例如 mysite.urls）。

• mysite/__init__.py：一个空文件，告诉 Python 这个目录应该被认为是一个 Python 包。 

• mysite/settings.py：Django 项目的配置文件。 

• mysite/urls.py：Django 项目的 URL 声明，就像你网站的“目录”。 

• mysite/asgi.py：作为你的项目的运行在 ASGI 兼容的 Web 服务器上的入口。 

• mysite/wsgi.py：作为你的项目的运行在 WSGI 兼容的Web服务器上的入口。 

用于开发的简易服务器

让我们验证你的 Django 项目是否正常工作。如果还没有进入 djangotutorial 目录，请先进入该目录，然后运行以下命令：

$ python manage.py runserver

你应该会看到如下输出：

Performing system checks...

System check identified no issues (0 silenced).

You have unapplied migrations; your app may not work properly until they are applied.
Run 'python manage.py migrate' to apply them.

二月 20, 2025 - 15:50:53
Django version 5.1, 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/ 。你将看到一个“祝贺”页面，有一只火箭正在发射。你成功了！

你已经启动了 Django 开发服务器，这是一个用纯 Python 编写的轻量级网络服务器。我们在 Django 中包含了这个服务器，所以你可以快速开发，而不需要处理配置生产服务器的问题 -- 比如 Apache -- 直到你准备好用于生产。

现在是个提醒你的好时机：千万不要 将这个服务器用于和生产环境相关的任何地方。这个服务器只是为了开发而设计的。（我们在网络框架方面是专家，在网络服务器方面并不是。）

创建投票应用

现在你的开发环境——这个“项目” ——已经配置好了，你可以开始干活了。

在 Django 中，每一个应用都是一个 Python 包，并且遵循着相同的约定。Django 自带一个工具，可以帮你生成应用的基础目录结构，这样你就能专心写代码，而不是创建目录了。

项目 VS 应用

项目和应用有什么区别？应用是一个专门做某件事的网络应用程序——比如博客系统，或者公共记录的数据库，或者小型的投票程序。项目则是一个网站使用的配置和应用的集合。项目可以包含很多个应用。应用可以被很多个项目使用。

你的应用程序可以位于Python路径中的任何位置。在本教程中，我们将在 djangotutorial 文件夹内创建我们的 poll 应用程序。

请确定你现在处于 manage.py 所在的目录下，然后运行这行命令来创建一个应用：

$ python manage.py startapp polls

这将创建一个名为 polls 的目录，其布局如下：

 
└── polls/               # 应用目录
    ├── migrations/      # 数据库迁移文件（自动生成）
    ├── __init__.py
    ├── admin.py         # 管理后台配置
    ├── apps.py          # 应用配置类
    ├── models.py        # 数据模型定义
    ├── tests.py         # 单元测试
    └── views.py         # 视图函数/类

 下面是一个较为完整的目录结构：

myproject/
├── manage.py
├── config/              # 项目配置目录（推荐替代默认的 myproject/）
│   ├── settings/        # 拆分不同环境的配置
│   │   ├── base.py      # 基础配置
│   │   ├── dev.py       # 开发环境
│   │   └── prod.py      # 生产环境
│   ├── urls.py          # 全局路由
│   ├── wsgi.py
│   └── __init__.py
├── apps/                # 集中存放所有应用
│   └── myapp/
│       ├── migrations/
│       ├── templates/   # 应用专属模板（推荐命名空间）
│       │   └── myapp/
│       │       └── index.html
│       ├── static/      # 应用专属静态文件
│       │   └── myapp/
│       │       └── style.css
│       ├── urls.py      # 应用路由
│       ├── views.py
│       └── ...
├── static/              # 项目级静态文件（公共 CSS/JS/图片）
├── templates/           # 项目级模板（如 base.html）
├── media/               # 用户上传文件（开发环境）
├── requirements/        # 依赖管理
│   ├── base.txt
│   ├── dev.txt
│   └── prod.txt
├── .env                 # 环境变量（如 SECRET_KEY）
├── .gitignore           # 忽略文件配置
└── README.md            # 项目文档

 

这个目录结构包括了投票应用的全部内容。

编写第一个视图

视图函数（或简称视图）是一种接受 Web 请求并返回 Web 响应的 Python 函数。 该响应可以是网页的 HTML 内容、重定向、404 错误、XML 文档、图像……或者任何东西。 视图本身包含返回该响应所需的任意逻辑。 该代码可以存在于您想要的任何地方，只要它位于您的 Python 路径上即可。 没有其他要求——可以说没有“魔法”。 为了将代码放置在某个地方，惯例是将视图放置在名为 views.py 的文件中，该文件放置在项目或应用程序目录中。

让我们开始编写第一个视图吧。打开 polls/views.py，把下面这些 Python 代码输入进去：

​
polls/views.py

from django.http import HttpResponse


def index(request):
    return HttpResponse("Hello, world. You're at the polls index.")
​

这是在 Django 中最基本的视图。要在浏览器中访问它，我们需要将其映射到一个 URL——为此我们需要定义一个 URL 配置，简称为 "URLconf"。这些 URL 配置是在每个 Django 应用程序内部定义的，它们是名为 urls.py 的 Python 文件。

要为 polls 应用定义一个 URLconf，创建一个名为 polls/urls.py 的文件，并包含以下内容：

polls/urls.py

from django.urls import path

from . import views

urlpatterns = [
    path("", views.index, name="index"),
]

你的应用目录现在应该如下所示：

polls/
    __init__.py
    admin.py
    apps.py
    migrations/
        __init__.py
    models.py
    tests.py
    urls.py
    views.py

下一步是在 mysite 项目中配置全局 URLconf，以包含在 polls.urls 中定义的 URLconf。为此，在 mysite/urls.py 中添加对 django.urls.include 的导入，并在 urlpatterns 列表中插入一个 include()，如下所示：

​
mysite/urls.py

from django.contrib import admin
from django.urls import include, path

urlpatterns = [
    path("polls/", include("polls.urls")),
    path("admin/", admin.site.urls),
]
​

path()​ 函数至少需要两个参数：route 和 view。include() 函数允许引用其他 URLconfs。每当 Django 遇到 include() 时，它会截断 URL 中匹配到该点的部分，并将剩余的字符串发送到包含的 URLconf 以进行进一步处理。

​ 我们设计 include() 的理念是使其可以即插即用。因为投票应用有它自己的 URLconf( polls/urls.py )，他们能够被放在 "/polls/" ， "/fun_polls/" ，"/content/polls/"，或者其他任何路径下，这个应用都能够正常工作。 何时使用 include() ​

当你包含其他 URL 模式时，应该始终使用 include()。唯一的例外是 admin.site.urls，这是 Django 为默认管理站点提供的预构建 URLconf。

你现在把 index 视图添加进了 URLconf。通过以下命令验证是否正常工作：

$ python manage.py runserver

用你的浏览器访问 http://localhost:8000/polls/，你应该能够看见 "Hello, world. You're at the polls index." ，这是你在 index 视图中定义的。