如何创建一个 Django 项目（译）

2026-08-16

Django 是一个功能丰富的 Python web 框架，但这并不代表它具有全部所需的功能。本文是一个构建和配置 Django 项目的实用指南，也包括了附加的库以及我的一些想法。本文的读者最好能有一些使用 Django 的经验。读者可以用官方教程温习一下 Django 的基础。

首先安装 uv ，然后使用这个命令创建一个虚拟库（virtual package）作为我们的项目（awesome_site）：

1uv init --virtual awesome_site

然后删除默认的 main.py 并创建新 Django 项目：

1cd awesome_site
2rm main.py
3uv add 'django==5.2.*'
4uv run django-admin startproject django_project

在上面的代码中，我安装了 Django 5.2 并创建了一个名为 django_project 的 Django 项目。

我安装 Django 5.2 的原因是 Django x.2 版本会得到3年的支持（LTS）。Django 长期支持版的大部分更新都是安全更新，而非功能更新，所以我们不需要频繁地重写我们的代码。不断地重写代码来追最新的 Django 版本是一项很繁琐的工作。

我虽然可以为上文的 Django 项目随意命名，但是仍把这个项目命名为 django_project，其中一个原因是 uv 创建的母项目 awesome_site 已经是我想要的项目名。另外一个原因是，在此项目中，Django 会在 django_project/django_project 目录储存配置文件，这样的项目名可以帮助我们快速找到配置文件目录。

额外的库

这几个库基本上是必需的：environs, django-taggit, django-extensions, django-debug-toolbar。

environs

读者可以使用这个命令安装 environs 库：

1uv add 'environs[django]'

environs 不仅可以读取系统环境变量和环境变量文件，还可以把这些值转换为合适的类型。比如，类型为 list 和 dict 的环境变量是这样表示的：

 1export GITHUB_REPOS=webargs,konch,ped
 2# in Python:
 3# print(env.list("GITHUB_REPOS"))
 4# ["webargs", "knoch", "ped"]
 5
 6
 7export GITHUB_REPO_PRIORITY="webargs=2,konch=3"
 8# in Python:
 9# print(env.dict("GITHUB_REPO_PRIORITY"))
10# {"webargs": "2", "konch: "3"}

有了 django 扩展，environs 可以把连接数据库的字符串转换为 Django 的数据库配置。比如：

1# Parse database URLs, e.g.  "postgres://localhost:5432/mydb"
2DATABASES = {"default": env.dj_db_url("DATABASE_URL")}

和下面的配置是等价的：

1DATABASES = {
2    'default': {
3        'ENGINE': 'django.db.backends.postgresql',
4        'NAME': 'mydb',
5        'HOST': 'localhost',
6        'PORT': '5432',
7    }
8}

django-taggit

django-taggit 可以给你的 Django 数据库模型类增加 TaggableManager 字段。读者用下面的命令来安装这个库：

1uv add 'django-taggit'

读者可以按照下面的例子来使用这个库：

1print(apple.tags.all())
2# []
3
4apple.tags.add("red", "green", "fruit")
5
6print(apple.tags.all())
7# ["red", "green", "fruit"]

django-extensions

django-extensions 是一个 Django 工具集。使用下面的命令来使用 uv 安装这个库：

1uv add django-extensions ipython

读者还需要把它加在 INSTALLED_APPS 列表中。INSTALLED_APPS 列表在这个文件中：django_project/django_project/settings.py：

1INSTALLED_APPS = (
2    # ...
3    "django_extensions",
4)

说实话，我只用这个库中的 shell_plus 扩展来自动载入数据库模型：

1uv run manage.py shell_plus

读者可以为上面的命令设置 ipython 解释器，方法是在 django_project/django_project/settings.py 中添加一行：

1SHELL_PLUS = "ipython"

这个库的文档也很有意思。

django-debug-toolbar 是一个不错的调试侧边栏。读者可以按照官方文档来安装这个库。

RESTful API 开发库

除了 Django REST Framework 库，读者还需要 dj-rest-auth 和 django-allauth 来实现健壮的认证和鉴权。读者可以阅读一下这些库的官方文档。

Web Socket 配置

首先安装 channels。 Channels 是一个 ASGI 独享库，这意味着读者只能在 ASGI 服务器上提供 Web Socket 路径。

然后配置 channels。首先创建一个协议路由来让 ASGI 服务器接受全部 TCP 连接（HTTP 和 Web Socket），然后再把HTTP请求交给原 Django 应用（application）来处理。再把 Web Socket 请求按照请求路径交由 Web Socket 消费者（consumer）类来处理。读者可以参考 channels 官方教程的具体步骤。

后台任务

后台任务依赖 celery 库。

在上面的项目中安装 celery 的方法是在 django_project/django_project 目录中创建一个 celery.py。在此文件中，初始化 Django 环境以及 celery 应用（application），并收集此项目中的所有后台任务。然后读者就可以同时启动 Django 和 celery 了。读者可以参照官方文档的具体步骤。