在 Windows 下搭建高效的 django 开发环境的详细教程

从初学 django 到现在（记得那时最新版本是 1.8，本文发布时已经发展到 3.1 了），开发环境一直都是使用从官方文档或者别的教程中学来的方式搭建的。但是在实际项目的开发中，越来越感觉之前的开发环境难以适应项目的发展。官方文档或一些教程中的环境搭建方式主要存在这些问题：

python manage.py runserver 启动的开发服务器热重载非常慢，尤其是当项目中导入了大量模块时，有时候改一次代码要等几秒钟才能完成重载。 主力开发环境为 Windows + PyCharm，然而有时候依赖的一些服务只能在 Linux 下运行（例如 Celery 以及其他一些异步任务的库如 django-q ）。

针对以上的一些痛点，我在实际开发当中逐步摸索出一套新的开发环境搭建方法，用来搭建一套舒适的 django 开发环境，总的来说，新的环境包括以下几个方面的改进：

• 使用 Uvicorn 代替 django 自带的开发服务器启动应用，极大提高代码热重载速度。
•  使用 Pipenv 或者 Poetry 来管理虚拟环境和项目依赖。
• 使用 Docker 容器来运行需要在 Linux 平台下才能运行的服务。
• 使用 AutoHotkey 为常用命令设置 alias。

PyCharm 创建 django 项目

Django 项目开发首选 PyCharm，当然你也可以使用 VS Code，不过极有可能随着一通折腾和配置之后，你会发现终于成功地把 VS Code 配置成了一个 PyCharm。所以为了节约有限的开发时间以及生命，推荐直接使用 PyCharm。

PyCharm 创建一个 django 项目非常简单，如果是第一次打开 PyCharm，点击 + Create New Project 就会弹出创建新项目的对话框。如果已经打开过别的项目，则依次点击顶部导航条的 File > New Project 也会弹出创建新项目的对话框。

然后在对话框左侧点击 django ，就会进入 django 项目的配置页面，完成一些初始化设置，PyCharm 就会自动为我们创建一个新的 django 项目。

Django 项目的配置页面如图：

Location配置项会让你选择项目位置，例如我要在 C:\Users\user\SpaceLocal\Workspace\G_Courses\ 目录下创建一个名为 django_dev_env_demo 的项目，就填写 C:\Users\user\SpaceLocal\Workspace\G_Courses\django-dev-env-demo 。

然后 Project Interpret 选项的展开项中有 2 个选项

• New environment using

勾选这个选项将使用你选择的虚拟环境创建工具为新建的项目创建一个 Python 虚拟环境。PyCharm 支持多种虚拟环境创建工具，默认为自带的 Virtualenv。我之前习惯使用 Pipenv，只需要在系统全局使用 pip install pipenv 后，PyCharm 就会自动发现 Pipenv 的存在。不过现在我更加倾向于使用 Poetry，PyCharm 目前还没有集成 Poetry，但是可以在创建完项目后手动设置 Poetry，配置也是超级简单，将在后面介绍。

创建新的虚拟环境需要指定一个 Base interpreter 基础 Python 环境，通常 PyCharm 会自动发现系统当前正在使用的 Python 解释器，如果 PyCharm 没有自动发现或者想要更换为系统中其它的 Python 解释器版本，也可以在 Base interpreter 选项里手动选择 Python 解释器。

使用 Pipenv 创建虚拟环境时，PyCharm 同样会自动发现系统中安装的 Pipenv 工具，如果没有发现，也可以在选项中手动选择。

• Existing interpreter

勾选这个选项将使用系统已有的 Python 环境。

More Settings选项的展开项中包含更多的 django 初始化设置：

• Template language

使用的模板引擎，如果没有特别理由，当然是选择 django 自带的模板引擎，当然不嫌麻烦也可以选择 jinja2。

• Template folder

存放模板的文件夹名称。默认即可，后续可以在项目中更改。

• Application name

django app 名称，填不填都行，后续可以使用 python manage.py startapp 命令来创建 django app。

勾选 Enable Django admin 将启用 django 自带的 admin 管理后台。

配置完成后，点击 Create 就可以创建一个全新的 django 项目了。

Uvicorn 运行 django

之前说过，django 内置的开发服务器在修改代码后的热重载非常缓慢，我发现 uvicorn 的重载速度要快得多，所以新项目第一件事，就是使用在开发环境下使用 uvicorn 运行 django。

首先当然要安装 uvicorn。

安装 uvicorn 非常简单，首先打开 PyCharm 的 Terminal，PyCharm 会自动帮我们激活项目关联的虚拟环境，所有命令将在虚拟环境执行，非常方便。执行 pipenv install uvicorn 安装 uvicorn 就可以了。

Uvicorn 安装好后，可以在命令行使用 uvicorn 命令来运行 django。但是，每次输命令启动 django 会非常麻烦！最好的做法是创建一个脚本，启动 django 只需要执行脚本就可以了。

在 项目根目录 创建一个 run_uvicorn.py 的脚本（脚本名可以自己随便取），代码如下：

run_uvicorn.py

import uvicorn
import os

def main():
 os.environ.setdefault("DJANGO_SETTINGS_MODULE", "django_dev_env_demo.settings")
 uvicorn.run(
  "django_dev_env_demo.asgi:application",
  host="0.0.0.0",
  port=8000,
  log_level="debug",
  reload=True,
 )

if __name__ == "__main__":
 main()

脚本中可以随意定制代码的逻辑，非常灵活。比如这里我首先设置了一个环境变量 DJANGO_SETTINGS_MODULE 用来指定 django 启动时加载的配置文件。举一反三，可以在 uvicorn.run 之前进行更多的设置。例如对于更加复杂的项目，我通常会把一些重要的路径加入到 sys.path 中，以及设置项目所需的环境变量。

然后就是 uvicorn.run 启动 django。更确切点地说就是启动一个 ASGI 或者 WSGI 应用。django 3 以后逐渐支持 ASGI 应用，而在此之前则是 WSGI。第一个参数传入 ASGI 或者 WSGI 应用所在的模块。例如这里的 django_dev_env_demo.asgi:application 表示 django_dev_env_demo 下 asgi.py 模块里的 application（django 提供的 ASGI 应用的实例），在 django_dev_env_demo/asgi.py 下可以看到。如果是 django 3.0 以前版本，相应改为 WSGI application 所在模块即可。

其它启动参数顾名思义，最为重要的就是这个 reload ，它启动热重载功能，比 django 自带的开发服务器重载快 很多。

PyCharm 执行一个 Python 脚本非常方便，点击 if __name__=="__main__" 旁边的绿色小三角就可以执行这个脚本，或者鼠标放到 run_uvicorn.py 上，然后点击鼠标右键，再点击 Run ‘run_uvicorn'。点击 Debug ‘run_uvicorn'，则以 debug 模式启动 django，开发过程中可以非常方便地打断点进行调试。

脚本运行后的输出：

说明应用已在 8000 端口启动，现在访问 localhost:8000，可以看到熟悉的 django 项目初始页面。

对于运行过的脚本，PyCharm 都会记录在右上角，以后只要在右上角的下拉框中选择需要执行的脚本，然后点击绿色三角或者 debug 按钮执行就可以了，非常方便！

Docker 运行外部服务

以前为了开发 django，我需要在系统中安装和配置各种服务，例如 MySQL、PostgreSQL、Redis、Elasticsearch，有些服务 Windows 还配不了，比如 Celery。

现在有了 Docker 容器，一切变得简单。

例如我需要一个 PostgreSQL，我只需要一条命令就可以启动一个 PostgreSQL 容器。当然更好的做法是编写一个 docker-compose 文件，并且设置该容器随 Docker 启动而启动，我系统中 PostgreSQL 服务的 Dockerfile 和docker-compose.yml 文件如下：

Dockerfile

FROM postgres:11.3

docker-compose.yml

version: '3'

volumes:
 postgres_data: {}
 postgres_data_backups: {}

services:
 postgres:
 restart: always
 build:
  context: .
 image: postgres
 container_name: postgres
 volumes:
  - postgres_data:/var/lib/postgresql/data
  - postgres_data_backups:/backups
 env_file:
  - postgres.env
 ports:
  - "14789:5432"

各项配置的含义请参考 Docker 的官方文档，实现的效果就是系统开机自启动 Docker，Docker 启动后自动启动一个运行着 PostgreSQL 数据库服务的容器，服务映射到主机的 14789 端口，这样，我的 django 或者其他应用程序都可以通过 host.docker.internal:14789 访问到 PostgreSQL 数据库服务。

最棒的是，PyCharm 还集成了数据库管理工具，无论是 SQLite 还是 MySQL 或者 PostgreSQL，都可以轻松连接，这样开发过程中就不需要使用额外的数据库可视化工具来查看开发数据了。

以 SQLite 为例，示例项目中运行 python manage.py migrate 命令创建数据库。

对于 SQLite 数据库，只需要双击数据库文件就可以直接连接，然后就能查看数据库表结构以及表中的数据了：

其它如 MySQL、PostgreSQL，只需要手动添加 Data Source 就可以连接。

类似的，Redis 现在几乎是开发必备，我会设置系统启动后也会自动启动一个 运行着 Redis 服务的容器。docker-compose.yml 文件内容如下：

version: '3'

services:
 redis:
 restart: always
 image: 'bitnami/redis:5.0'
 container_name: redis
 ports:
  - '48988:6379'
 volumes:
  - 'redis_data:/bitnami/redis/data'
 env_file:
  - redis.env

volumes:
 redis_data:
 driver: local

服务映射到主机的 48988 端口，这样，我的 django 或者其他应用程序都可以通过 host.docker.internal:48988 访问到 redis 服务。

其它任何服务都可以类似地配置，例如 Elasticsearch、Celery 等等。

AutoHotkey

开发过程中难免需要输入大量命令，比如 django 中的这几条使用频率极高：

python manage.py makemigrations
python manage.py migrate
python manage.py createsuperuser

重复输入这些命令单调又枯燥，还浪费生命。

AutoHotkey 的其中一个功能是为指定的文本设置缩写词，并使用热键将缩写词展开为全文本。例如我会为以上命令设置缩写词：

python manage.py makemigrations 设置为 pmmm，按 tab 键展开
python manage.py migrate 设置为 pmm，按 tab 键展开
python manage.py createsuperuser 设置为 pmcs，按 tab 键展开

我只需要在命令行输入 pmmm 再按 tab，AutoHotkey 就会将其展开为 python manage.py makemigrations 的完整命令。

当然，AutoHotkey 的功能远不止如此，还可以用来设置快捷打开常用网站，常用文件夹等等，现在已是我在 Windows 下节约不少生命值的效率工具。

使用 Poetry？

Poetry 与 Pipenv 的争议

当年关于 Pipenv 还是 Poetry 曾引发过不少争议。《Flask Web 开发实战》的作者发文呼吁大家 不要用 Pipenv ，并列举了不少 Pipenv 存在的问题。

Pipenv 的确存在不少如文中所说的问题，很多问题 issue 维护者给出的建议是请安装 master 分支的代码。

在体验了 Poetry 以后，我发现迁移 Poetry 并非一件困难的事，而且对于日常使用来说，Poetry 一样简单易用，所以目前对于新的项目，我都会优先使用 Poetry。

当然话说回来，Pipenv 的一些问题都是一些特殊环境下的问题，这些问题 Poetry 同样也会存在。对于一般的使用场景，我并未发现 Pipenv 和 Poetry 的使用区别。

所以总结一句话，我的使用原则是：

优先用 Poetry，但对于一些小项目或者示例项目，为了更好地和 PyCharm 配合，我也会使用 Pipenv。

PyCharm 中设置 Poetry

PyCharm 中设置 Poetry 非常简单。当然首先第一步是安装 Poetry，安装也是超级简单，各种操作系统平台都是一条命令搞定，安装命令可参考 Poetry 的 官方文档 。

Poetry 安装后，在项目根目录执行 poetry init 命令初始化项目，依据提示输入初始化设置后，poetry 会在项目根目录生成 pyproject.toml 项目描述文件。内容大概是这样：

[tool.poetry]
name = "django_dev_env_demo"
version = "0.1.0"
description = ""
authors = ["zmrenwu <zmrenwu@163.com>"]

[tool.poetry.dependencies]
python = "^3.7"

[tool.poetry.dev-dependencies]

[build-system]
requires = ["poetry>=0.12"]
build-backend = "poetry.masonry.api"

安装依赖可以使用 add 命令，例如要添加 django 依赖：

$ poetry add django

poetry 会自动将依赖写入 pyproject.toml 项目描述文件， [tool.poetry.dependencies] 的内容变成了这样：

[tool.poetry.dependencies]
python = "^3.7"
django = "^3.0.3"

如果是开发环境下的依赖，和 Pipenv 类似，可以加 --dev 参数标记为开发环境依赖包：

$ poetry add pytest pytest-django --dev

Poetry 会自动将依赖写入 pyproject.toml 项目描述文件， [tool.poetry.dev-dependencies] 的内容变成了这样：

[tool.poetry.dev-dependencies]
pytest = "^5.3.5"
pytest-django = "^3.8.0"

为了 PyCharm 自动使用 poetry 创建的虚拟环境，需要在项目中配置 Python 解释器为 poetry 创建的虚拟环境中的解释器。

首先运行下面的命令输出创建的虚拟环境所在位置：

$ poetry env info --path
C:\Users\user\.virtualenvs\django_dev_env_demo-frkNfPtg

PyCharm 中：File -> Settings -> Porject: django_dev_env_demo -> Project Interpreter。

点击右上角的齿轮，再点击 Add 添加虚拟环境，选择 Existing environment，再点击 Interpreter 后面的省略号，选择 poetry env info --path 输出的虚拟环境路径下的 Scripts/python.exe 作为解释器。

然后点击 ok 确认就 ok 了。

这样，在使用 PyCharm 的 Terminal 时，就会自动激活 poetry 创建的虚拟环境，和用 Pipenv 创建的虚拟环境一样。

总结

这里给大家展示了如何使用 PyCharm + Uvicorn + Docker + AutoHotkey + Pipenv or Poetry 搭建舒适的 django 开发环境，基本上能满足大部分不是很复杂的项目。

要记住，无论以什么样的方式搭建开发环境，核心目的只有一个： 让开发者只需关注核心业务逻辑的开发，而不是被各种环境问题分心。

当然，对于一些更加复杂的项目，在此基础上我们还可以进一步优化环境的配置来满足各种复杂的环境要求，我会在以后的文章里进行进一步地介绍。