编写你的第一个 Django 应用，第 1 部分¶
让我们通过示例来学习。
通过这个教程，我们将带着你创建一个基本的投票应用程序。
它将由两部分组成：
一个让人们查看和投票的公共站点。
一个让你能添加、修改和删除投票的管理站点。
我们假定你已经阅读了 安装 Django。你能知道 Django 已被安装，且安装的是哪个版本，通过在命令提示行输入命令（由 $ 前缀）。
$ python -m django --version
...\> py -m django --version
如果这行命令输出了一个版本号，证明你已经安装了此版本的 Django；如果你得到的是一个“No module named django”的错误提示，则表明你还未安装。
This tutorial is written for Django 6.0, which supports Python 3.12 and later. If the Django version doesn't match, you can refer to the tutorial for your version of Django by using the version switcher at the bottom right corner of this page, or update Django to the newest version. If you're using an older version of Python, check 我应该使用哪个版本的 Python 来配合 Django? to find a compatible version of Django.
从哪里获得帮助：
如果你在阅读本教程的过程中有任何疑问，可以前往 FAQ 的 获取帮助 的版块。
创建项目¶
如果这是你第一次使用 Django 的话，你需要一些初始化设置。也就是说，你需要用一些自动生成的代码配置一个 Django project —— 即一个 Django 项目实例需要的设置项集合，包括数据库配置、Django 配置和应用程序配置。
From the command line, cd into a directory where you'd like to store your
code and run the following command to bootstrap a new Django project:
$ django-admin startproject mysite djangotutorial
...\> django-admin startproject mysite djangotutorial
This will create a directory djangotutorial with a project called
mysite inside. The directory name doesn't matter to Django; you can rename
it to anything you like. If it didn't work, see
运行 django-admin 时遇到的问题.
Note
你得避免使用 Python 或 Django 的内部保留字来命名你的项目。具体地说，你得避免使用像 django (会和 Django 自己产生冲突)或 test (会和 Python 的内置组件产生冲突)这样的名字。
让我们看看 startproject 创建了些什么：
djangotutorial/
manage.py
mysite/
__init__.py
settings.py
urls.py
asgi.py
wsgi.py
这些目录和文件的用处是：
manage.py: 一个让你用各种方式管理 Django 项目的命令行工具。你可以阅读 django-admin 和 manage.py 获取所有manage.py的细节。mysite/: 一个目录，它是你项目的实际 Python 包。它的名称是你需要用来导入其中任何内容的 Python 包名称（例如mysite.urls）。mysite/__init__.py：一个空文件，告诉 Python 这个目录应该被认为是一个 Python 包。如果你是 Python 初学者，阅读官方文档中的 更多关于包的知识。mysite/settings.py: Settings/configuration for this Django project. Django 配置 will tell you all about how settings work.mysite/urls.py：Django 项目的 URL 声明，就像你网站的“目录”。阅读 URL调度器 文档来获取更多关于 URL 的内容。mysite/asgi.py：作为你的项目的运行在 ASGI 兼容的 Web 服务器上的入口。阅读 如何使用 ASGI 来部署 了解更多细节。mysite/wsgi.py：作为你的项目的运行在 WSGI 兼容的Web服务器上的入口。阅读 如何使用 WSGI 进行部署 了解更多细节。
用于开发的简易服务器¶
让我们验证你的 Django 项目是否正常工作。如果还没有进入 djangotutorial 目录，请先进入该目录，然后运行以下命令：
$ python manage.py runserver
...\> 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. 十二月 03, 2025 - 15:50:53 Django version 6.0, 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/6.0/howto/deployment/
Note
忽略有关未应用最新数据库迁移的警告，稍后我们处理数据库。
服务器现在正在运行，通过浏览器访问 http://127.0.0.1:8000/ 。你将看到一个“祝贺”页面，有一只火箭正在发射。你成功了！
你已经启动了 Django 开发服务器，这是一个用纯 Python 编写的轻量级网络服务器。我们在 Django 中包含了这个服务器，所以你可以快速开发，而不需要处理配置生产服务器的问题 -- 比如 Apache -- 直到你准备好用于生产。
现在是个提醒你的好时机：千万不要 将这个服务器用于和生产环境相关的任何地方。这个服务器只是为了开发而设计的。（我们在网络框架方面是专家，在网络服务器方面并不是。）
(若要在一个不同的端口上提供网站服务，请参阅 runserver 参考。)
会自动重新加载的服务器 runserver
用于开发的服务器在需要的情况下会对每一次的访问请求重新载入一遍 Python 代码。所以你不需要为了让修改的代码生效而频繁的重新启动服务器。然而，一些动作，比如添加新文件，将不会触发自动重新加载，这时你得自己手动重启服务器。
创建投票应用¶
现在你的开发环境——这个“项目” ——已经配置好了，你可以开始干活了。
在 Django 中，每一个应用都是一个 Python 包，并且遵循着相同的约定。Django 自带一个工具，可以帮你生成应用的基础目录结构，这样你就能专心写代码，而不是创建目录了。
项目 VS 应用
项目和应用有什么区别？应用是一个专门做某件事的网络应用程序——比如博客系统，或者公共记录的数据库，或者小型的投票程序。项目则是一个网站使用的配置和应用的集合。项目可以包含很多个应用。应用可以被很多个项目使用。
你的应用程序可以位于 Python 路径 中的任何位置。在本教程中，我们将在 djangotutorial 文件夹内创建我们的 poll 应用程序。
请确定你现在处于 manage.py 所在的目录下，然后运行这行命令来创建一个应用：
$ python manage.py startapp polls
...\> py manage.py startapp polls
这将创建一个名为 polls 的目录，其布局如下：
polls/
__init__.py
admin.py
apps.py
migrations/
__init__.py
models.py
tests.py
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
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() in the urlpatterns list, so you have:
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/"，或者其他任何路径下，这个应用都能够正常工作。
When to use include()
当你包含其他 URL 模式时，应该始终使用 include()。唯一的例外是 admin.site.urls，这是 Django 为默认管理站点提供的预构建 URLconf。
你现在把 index 视图添加进了 URLconf。通过以下命令验证是否正常工作：
$ python manage.py runserver
...\> 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 部分 开始使用数据库.
