Python · 4 分钟阅读

1. Flask 简介

什么是 Flask
项目结构约定
安装
常见问题
下一步

什么是 Flask

Flask 是一个用 Python 编写的轻量级 Web 框架。它由 Armin Ronacher 创建，遵循
Werkzeug（WSGI 工具库）和 Jinja2（模板引擎）两个核心依赖，以“微框架”的
姿态提供 Web 开发所需的最小组件：

能力	由谁提供	备注
路由 / WSGI	Werkzeug	HTTP 请求解析、URL 匹配、服务器网关接口
模板渲染	Jinja2	变量插值、控制流、模板继承
表单 / 数据库	不内置	通过扩展按需引入
用户认证 / 授权	不内置	通过扩展按需引入

这种“微内核 + 生态扩展”的设计让 Flask 既适合写一个 hello world，也适合搭建
中大型应用。新手可以在熟悉之后再逐步引入 Flask-SQLAlchemy、Flask-Login、
Flask-Migrate 等扩展。

截至 2026 年，Flask 主版本为 3.x，要求 Python ≥ 3.9（推荐 3.11+）。本文示例
均基于 Flask 3.x 与 Python 3.11。

项目结构约定

一个最小可维护的 Flask 项目通常长这样：

my-flask-app/
├── pyproject.toml          # 项目元数据与依赖（推荐使用 uv / poetry / pip-tools）
├── .venv/                  # 虚拟环境目录（被 .gitignore 忽略）
├── app/
│   ├── __init__.py         # create_app() 应用工厂
│   ├── blueprints/         # 按业务拆分的蓝图
│   ├── templates/          # Jinja2 模板
│   └── static/             # CSS / JS / 图片等静态资源
├── tests/                  # pytest 测试
└── README.md

初学阶段可以先只用单文件 app.py，熟悉后再迁移到“应用工厂 + 蓝图”结构。

安装

强烈建议：始终在虚拟环境中安装 Python 包，避免污染系统解释器，也避免
“这台机器能跑、那台机器跑不起来”的依赖冲突。

1. 准备 Python

确保已安装 Python 3.10 或更高版本：

python3 --version
# Python 3.11.x

如果系统没有，可通过以下任一方式获取：

官方安装包：https://www.python.org/downloads/
macOS：brew install python@3.12
Windows：勾选 “Add Python to PATH” 一键安装

2. 创建并激活虚拟环境

方式 A：`python -m venv`（Python 内置，零依赖）

# macOS / Linux
python3 -m venv .venv
source .venv/bin/activate

# Windows (PowerShell)
python -m venv .venv
.venv\Scripts\Activate.ps1

方式 B：uv（推荐，速度极快）

# 安装 uv
pip install uv

# 创建虚拟环境
uv venv .venv
source .venv/bin/activate

# 安装依赖（写入 pyproject.toml）
uv add flask

方式 C：Poetry

poetry init
poetry add flask
poetry shell

激活虚拟环境后，命令行提示符会带上 (.venv) 前缀。退出虚拟环境：
deactivate

3. 安装 Flask

pip install -U flask

或使用 uv：

uv add flask

4. 验证安装

python -c "import flask, sys; print(flask.__version__, sys.version_info[:2])"
# 期望输出形如：3.0.x (3, 11)

或者写一个 hello.py：

from flask import Flask

app = Flask(__name__)

@app.get("/")
def index():
    return "<h1>Hello, Flask!</h1>"

启动并访问 http://127.0.0.1:5000：

# 方式 1：传统
python hello.py

# 方式 2（推荐）：使用 Flask 内置 CLI
flask --app hello run --debug

--debug 会开启调试模式：代码改动自动重载、出错时显示交互式 traceback。
⚠️ 生产环境绝不能开启 debug 模式。

5. 管理依赖（可选但推荐）

把依赖固化到 requirements.txt：

pip freeze > requirements.txt
# 别人安装时：
pip install -r requirements.txt

更现代的做法是使用 pyproject.toml + pip-compile / uv lock / poetry.lock
锁定版本，避免“在我电脑上能跑”问题。

常见问题

flask 命令找不到 → 当前目录没有 app.py / wsgi.py，
或未通过 pip install flask 安装。解决：使用 flask --app hello run 显式指定。
Address already in use → 5000 端口被占用，换端口：
flask run --port 5050，或者找到占用进程并结束。
改代码没生效 → 检查是否启用了 --debug；生产部署应使用 gunicorn /
uvicorn 等 WSGI/ASGI 服务器，文件改动不会自动重载。