---
title: "编写你的第一个 Django 应用，第 1 部分"
version: 5.2
locale: zh-hans
source: https://docs.djangoproject.com/zh-hans/5.2/intro/tutorial01/
canonical: https://djangodocs.dev/zh-hans/5.2/intro/tutorial01/
---
# 编写你的第一个 Django 应用，第 1 部分

让我们通过示例来学习。

通过这个教程，我们将带着你创建一个基本的投票应用程序。

它将由两部分组成：

- 一个让人们查看和投票的公共站点。
- 一个让你能添加、修改和删除投票的管理站点。

我们假定你已经阅读了 [安装 Django](/zh-hans/5.2/intro/install/)。你能知道 Django 已被安装，且安装的是哪个版本，通过在命令提示行输入命令（由 $ 前缀）。

```console
$ python -m django --version
```

*Windows*

```doscon
...\> py -m django --version
```

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

本教程适用于 Django 5.2，支持 Python 3.10 及更高版本。如果 Django 版本不匹配，您可以使用本页面右下角的版本切换器查看适用于您 Django 版本的教程，或者将 Django 更新到最新版本。如果您使用的是较旧版本的 Python，请查看 [我应该使用哪个版本的 Python 来配合 Django?](/zh-hans/5.2/faq/install/#faq-python-version-support) 以找到与之兼容的 Django 版本。

> **从哪里获得帮助：**
>
> 如果你在阅读本教程的过程中有任何疑问，可以前往 FAQ 的 [获取帮助](/zh-hans/5.2/faq/help/) 的版块。

## 创建项目

如果这是你第一次使用 Django 的话，你需要一些初始化设置。也就是说，你需要用一些自动生成的代码配置一个 Django [project](/zh-hans/5.2/glossary/#term-project) —— 即一个  Django 项目实例需要的设置项集合，包括数据库配置、Django 配置和应用程序配置。

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

```console
$ mkdir djangotutorial
```

*Windows*

```doscon
...\> mkdir djangotutorial
```

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

```console
$ django-admin startproject mysite djangotutorial
```

*Windows*

```doscon
...\> django-admin startproject mysite djangotutorial
```

这将在 `djangotutorial` 目录内创建一个名为 `mysite` 的项目。如果没有成功，请参阅 [运行 django-admin 时遇到的问题](/zh-hans/5.2/faq/troubleshooting/#troubleshooting-django-admin)。

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

让我们看看 [`startproject`](/zh-hans/5.2/ref/django-admin/#django-admin-startproject) 创建了些什么：

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

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

- `manage.py`: 一个让你用各种方式管理 Django 项目的命令行工具。你可以阅读 [django-admin 和 manage.py](/zh-hans/5.2/ref/django-admin/) 获取所有 `manage.py` 的细节。
- `mysite/`: 一个目录，它是你项目的实际 Python 包。它的名称是你需要用来导入其中任何内容的 Python 包名称（例如 `mysite.urls`）。
- `mysite/__init__.py`：一个空文件，告诉 Python 这个目录应该被认为是一个 Python 包。如果你是 Python 初学者，阅读官方文档中的 [更多关于包的知识](https://docs.python.org/3/tutorial/modules.html#tut-packages)。
- `mysite/settings.py`：Django 项目的配置文件。如果你想知道这个文件是如何工作的，请查看 [Django 配置](/zh-hans/5.2/topics/settings/) 了解细节。
- `mysite/urls.py`：Django 项目的 URL 声明，就像你网站的“目录”。阅读 [URL调度器](/zh-hans/5.2/topics/http/urls/) 文档来获取更多关于 URL 的内容。
- `mysite/asgi.py`：作为你的项目的运行在 ASGI 兼容的 Web 服务器上的入口。阅读 [如何使用 ASGI 来部署](/zh-hans/5.2/howto/deployment/asgi/) 了解更多细节。
- `mysite/wsgi.py`：作为你的项目的运行在 WSGI 兼容的Web服务器上的入口。阅读 [如何使用 WSGI 进行部署](/zh-hans/5.2/howto/deployment/wsgi/) 了解更多细节。

## 用于开发的简易服务器

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

```console
$ python manage.py runserver
```

*Windows*

```doscon
...\> py 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.

8月 09, 2026 - 15:50:53
Django version 5.2, using settings 'mysite.settings'
Starting development server at http://127.0.0.1:8000/
Quit the server with CONTROL-C.

WARNING: This is a development server. Do not use it in a production setting. Use a production WSGI or ASGI server instead.
For more information on production servers see: https://docs.djangoproject.com/en/5.2/howto/deployment/
```

> **Note**
>
> 忽略有关未应用最新数据库迁移的警告，稍后我们处理数据库。

服务器现在正在运行，通过浏览器访问 <http://127.0.0.1:8000/> 。你将看到一个“祝贺”页面，有一只火箭正在发射。你成功了！

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

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

(若要在一个不同的端口上提供网站服务，请参阅 [`runserver`](/zh-hans/5.2/ref/django-admin/#django-admin-runserver) 参考。)

> **会自动重新加载的服务器 runserver**
>
> 用于开发的服务器在需要的情况下会对每一次的访问请求重新载入一遍 Python 代码。所以你不需要为了让修改的代码生效而频繁的重新启动服务器。然而，一些动作，比如添加新文件，将不会触发自动重新加载，这时你得自己手动重启服务器。

## 创建投票应用

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

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

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

你的应用程序可以位于 [Python 路径](https://docs.python.org/3/tutorial/modules.html#tut-searchpath) 中的任何位置。在本教程中，我们将在 `djangotutorial` 文件夹内创建我们的 poll 应用程序。

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

```console
$ python manage.py startapp polls
```

*Windows*

```doscon
...\> py manage.py startapp polls
```

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

```text
polls/
    __init__.py
    admin.py
    apps.py
    migrations/
        __init__.py
    models.py
    tests.py
    views.py
```

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

## 编写第一个视图

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

*`polls/views.py`*

```python
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`*

```python
from django.urls import path

from . import views

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

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

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

The next step is to configure the root URLconf in the `mysite` project to
include the URLconf defined in `polls.urls`. To do this, add an import for
`django.urls.include` in `mysite/urls.py` and insert an
[`include()`](/zh-hans/5.2/ref/urls/#django.urls.include) in the `urlpatterns` list, so you have:

*`mysite/urls.py`*

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

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

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

我们设计 [`include()`](/zh-hans/5.2/ref/urls/#django.urls.include) 的理念是使其可以即插即用。因为投票应用有它自己的 URLconf( `polls/urls.py` )，他们能够被放在 "/polls/" ， "/fun\_polls/" ，"/content/polls/"，或者其他任何路径下，这个应用都能够正常工作。

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

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

```console
$ python manage.py runserver
```

*Windows*

```doscon
...\> py manage.py runserver
```

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

> **没有找到页面?**
>
> 如果你在这里得到了一个错误页面，检查一下你是不是正访问着http://localhost:8000/polls/ 而不应该是  http://localhost:8000/。

当你了解了基本的请求和响应流程后，请阅读 [教程的第 2 部分](/zh-hans/5.2/intro/tutorial02/)  开始使用数据库.