Flask 安装与环境配置指南：从 Python 版本要求到依赖体系全解析

Flask 的安装过程本身很轻量，但其背后涉及明确的 Python 版本约束、一组精心选择的运行时依赖，以及围绕 flask 命令行工具构建的开发工作流。本文基于当前仓库的官方安装文档 docs/installation.rst，结合 pyproject.toml 中的真实依赖声明与 src/flask/cli.py 等源码实现，系统讲解：如何正确搭建 Python 虚拟环境、安装 Flask 及其六大核心依赖各自承担的角色、可选依赖（python-dotenv、Watchdog）如何被自动检测与启用，以及在 gevent 场景下的 greenlet/PyPy 版本要求。读完本文，你将能够独立完成一次可复现、可验证的 Flask 环境搭建，并理解每个依赖在框架中的实际作用。

Python 版本要求

官方安装文档的建议是：使用最新的 Python 版本，Flask 支持 Python 3.10 及更高版本。

这一表述在仓库的打包配置中有明确印证。pyproject.toml 中声明：

requires-python = ">=3.10"

同时，项目通过 tox 定义了完整的测试矩阵（pyproject.toml），覆盖 Python 3.10 到 3.15（含 3.14t 自由线程版本）以及 PyPy 3.11：

[tool.tox]
env_list = [
    "py3.15",
    "py3.14", "py3.14t",
    "py3.13", "py3.12", "py3.11", "py3.10",
    "pypy3.11",
    "tests-min", "tests-dev",
    "style",
    "typing",
    "docs",
]

适用前提说明：这意味着 Python 3.9 及以下版本不在支持范围内；静态类型检查（mypy/pyright）也以 python_version = "3.10" 为基准（pyproject.toml）。如果你还在维护老版本 Python 的项目，Flask 新版本无法直接安装使用。

核心依赖：安装 Flask 时会一并装上什么

执行 pip install Flask 时，以下六个发行版会被自动安装。它们的版本下限由 pyproject.toml 中的 dependencies 精确锁定：

依赖	最低版本	在 Flask 中的角色
Werkzeug	>=3.1.0	实现 WSGI，即 Python 应用与 Web 服务器之间的标准接口
Jinja2	>=3.1.2	模板语言，负责渲染应用对外提供的页面
MarkupSafe	>=2.1.1	随 Jinja 附带，在渲染模板时转义不可信输入，防止注入攻击
ItsDangerous	>=2.2.0	对数据进行安全签名以保证完整性，Flask 用它保护 session cookie
Click	>=8.1.3	命令行应用框架，提供 flask 命令并允许添加自定义管理命令
Blinker	>=1.9.0	提供 信号（signals） 支持

对应源码声明：

dependencies = [
    "blinker>=1.9.0",
    "click>=8.1.3",
    "itsdangerous>=2.2.0",
    "jinja2>=3.1.2",
    "markupsafe>=2.1.1",
    "werkzeug>=3.1.0",
]

这些不是任意版本即可，仓库还通过专门的 tox 环境 tests-min 在最低依赖版本组合（blinker==1.9.0、click==8.1.3、itsdangerous==2.2.0、jinja2==3.1.2、markupsafe==2.1.1、werkzeug==3.1.0）上运行完整测试套件（pyproject.toml），确保声明的版本下限真实可用。

值得留意的两点

MarkupSafe 的独立地位。文档将 MarkupSafe 描述为“随 Jinja 附带”，因为它确实是 Jinja2 的依赖；但 Flask 在 pyproject.toml 中同时显式声明了对它的依赖，说明框架自身也直接使用 Markup 等类型（例如在视图返回值与模板引擎之间的安全标记传递），并非仅通过 Jinja 间接受益。

依赖版本的定位。文档强调：这些是“首次加入所需特性的版本”，并非最低支持版本意义上的承诺区间，你应该使用各依赖的最新版本。这一表述与 tests-dev 环境（用各依赖的 main 分支开发版做前向兼容测试，pyproject.toml）的设计思路一致。

可选依赖：Flask 会主动检测并使用

以下两个发行版不会随 Flask 自动安装，但一旦你手动安装了它们，Flask 会自动检测并启用相应能力。

python-dotenv：启用 flask 命令的 dotenv 支持

安装 python-dotenv 后，运行 flask run 等命令时会自动加载最近的 .env 与 .flaskenv 文件来设置环境变量。其实现逻辑位于 src/flask/cli.py 的 load_dotenv() 函数，从源码可以直接读出几个关键行为：

• 优先级规则：通过 -e/--env-file 显式指定的路径 > .env > .flaskenv，加载合并后，仅当键在 os.environ 中尚不存在时才写入，即真正的 shell 环境变量始终拥有最高优先级；
• 未安装时的降级处理：import dotenv 失败时函数直接返回 False 不报错；但如果检测到当前目录存在 .env 或 .flaskenv 文件，会通过 Click 向 stderr 打印一条黄色提示 “There are .env files present. Install python-dotenv to use them.”，提醒你补装；
• 编码：加载时使用 UTF-8 编码（2.0 起的默认行为）。

该函数的调用入口在 ScriptInfo 中（src/flask/cli.py），并由 src/flask/app.py 中 Flask.run() 通过 get_load_dotenv() 决定是否触发（默认 load_dotenv=True）。另外，pyproject.toml 提供了官方 extra，方便一条命令带上它：

[project.optional-dependencies]
async = ["asgiref>=3.2"]
dotenv = ["python-dotenv"]

因此也可以写成 pip install "Flask[dotenv]"。

Watchdog：更快的开发服务器 reloader

flask run 在 debug 模式下默认启用文件监视 reloader（src/flask/cli.py 提供 --reload/--no-reload 选项，默认跟随 --debug）。安装 Watchdog 后，reloader 可从基于轮询的监视切换为基于操作系统文件事件的通知方式，在大型项目中获得更快、更高效的变更检测。

gevent 场景：greenlet 与 PyPy 的版本要求

如果你选择用 Gevent 来运行应用（以获得无需编写 async def 即可处理大量长连接并发的方式），安装文档给出的额外约束是：

• 需要 greenlet >= 1.0；
• 如果使用 PyPy，则需要 PyPy >= 7.3.7。

文档特意提醒：这些不是最低支持版本，只是“首次加入所需特性的版本”，你应该使用各项目的最新版本。

gevent 的接入方式是在项目模块或顶层 __init__.py 的最前面尽早执行 gevent.monkey.patch_all()；生产部署则建议配合 gunicorn 或 uWSGI 的 gevent worker 使用（见 docs/gevent.rst）。Gevent 的底层正是 greenlet 协程机制，这与 Flask 上下文栈中对 greenlet/gevent 兼容性的注释（src/flask/ctx.py）相互呼应。

使用虚拟环境管理项目依赖

安装文档强烈建议：无论在开发还是生产环境，都使用虚拟环境来管理项目依赖。

它解决的问题很具体：你接触的 Python 项目越多，就越可能在同一台机器上需要不同版本的库、甚至不同版本的 Python 本身——某个项目升级了某库，就可能打破另一个项目的兼容性。虚拟环境是每个项目独立的一组 Python 库，为项目 A 安装的包不会影响项目 B，也不会污染操作系统的系统级包。

Python 标准库自带 venv 模块来创建虚拟环境，无需安装任何额外工具。

创建环境

创建项目文件夹，并在其中创建 .venv 虚拟环境文件夹：

macOS / Linux：

$ mkdir myproject
$ cd myproject
$ python3 -m venv .venv

Windows：

> mkdir myproject
> cd myproject
> py -3 -m venv .venv

激活环境

每次开始处理该项目前，先激活对应的环境：

macOS / Linux：

$ . .venv/bin/activate

Windows：

> .venv\Scripts\activate

激活后，shell 提示符会显示当前激活的环境名，这是一个直观的状态指示，能帮你避免“在错误环境里安装包”这类常见事故。

安装 Flask 并验证

在已激活的虚拟环境中执行：

$ pip install Flask

Flask 安装完成。可以用 --version 确认安装结果：

$ flask --version

这里顺带说明 flask 命令从何而来：它并非 Flask 包内的可执行脚本，而是 pyproject.toml 中声明的 console 入口点：

[project.scripts]
flask = "flask.cli:main"

即安装后由 pip 生成的命令入口指向 src/flask/cli.py 中的 main 对象——这就是上文提到的 Click 依赖的直接体现，也是后续 flask run、flask shell、flask routes 等命令的总入口。

验证无误后，即可继续阅读 快速入门，或回到 文档总览 了解路由、模板、错误处理等后续主题。

小结

• 版本底线：Python >=3.10（pyproject.toml），建议始终使用最新 Python；
• 六个必装依赖各司其职：Werkzeug 提供 WSGI、Jinja2 渲染模板、MarkupSafe 防注入、ItsDangerous 保护 session、Click 承载 flask CLI、Blinker 支持信号；
• 两个可选依赖按需安装、自动生效：python-dotenv 让 flask 命令读取 .env/.flaskenv，Watchdog 加速开发服务器 reloader；
• gevent 用户注意 greenlet >= 1.0、PyPy >= 7.3.7 的特性起点约束；
• 全程使用 venv 虚拟环境，保证开发与生产依赖隔离、可复现。