使用 Poetry + VS Code 创建你的第一个 Flask 工程

本篇博客同样隶属于勇闯前后端系列的Python博客系列

我见过使用Python来入门后端框架的朋友，基本上选择就是Flask或者是FastAPI，为此，笔者这里决定单独开几个重要的博客，详细的阐述如何使用Poetry + VSCode来创建我们的第一个Flask工程。

基本上，这篇博客期望完成：

环境准备（WSL + Python + Poetry）
使用 Poetry 初始化 Flask 项目
创建最小 Flask 程序
使用 poetry run / poetry shell 启动应用
配置 VS Code 自动选择 Poetry 虚拟环境
推荐的项目结构
常见问题 & 解决方案
官方参考资料

适合希望将 Flask 工程化、专业化开发的同学。

1. 🧱 准备环境

笔者喜欢的是WSL，这里，关于WSL如何安装笔者不计划重复了，自行搜索引擎。

检查 Python 版本（建议 3.10+）

bash 复制代码

python3 --version

确认 Poetry 已安装

bash 复制代码

poetry --version

如果未安装，可以用官方安装脚本，当然，笔者优先建议你好好看一看教程，poetry还是很好用的

Introduction | Documentation | Poetry - Python dependency management and packaging made easy

bash 复制代码

curl -sSL https://install.python-poetry.org | python3 -

2. 📦 用 Poetry 创建 Flask 项目

进入你想存放项目的目录：

bash 复制代码

mkdir flask-demo
cd flask-demo

初始化 Poetry 项目

bash 复制代码

poetry init --no-interaction

这会生成 pyproject.toml。

安装 Flask

bash 复制代码

poetry add flask

Poetry 会自动创建一个虚拟环境存放依赖。

检查虚拟环境路径：

bash 复制代码

poetry env info --path

你会看到类似：

复制代码

/home/xxx/.cache/pypoetry/virtualenvs/flask-demo-py3.11

3. 📝 创建最小 Flask Demo

在项目根目录创建 app.py：

python 复制代码

from flask import Flask

app = Flask(__name__)

@app.route("/")
def hello():
    return "<h1>Hello, Flask (from Poetry)!</h1>"

if __name__ == "__main__":
    app.run(host="0.0.0.0", port=5000, debug=True)

这是 Flask 官方 quickstart 的最小版本。

▶️ 启动 Flask 应用（3 种方式）

下面是 Poetry 中最常用、最稳定的运行方式。

✔ 方法 A：在 Poetry 虚拟环境中运行

进入 Poetry shell：

bash 复制代码

poetry shell
python app.py

✔ 方法 B：不进入 shell，直接运行

bash 复制代码

poetry run python app.py

或使用 Flask CLI：

bash 复制代码

poetry run flask --app app --debug run

--debug 会自动开启热重载。

✔ 方法 C：写到 pyproject 里（可选）

编辑 pyproject.toml：

toml 复制代码

[tool.poetry.scripts]
run-app = "app:app"

然后运行：

bash 复制代码

poetry run run-app

🧩 配置 VS Code 自动选择 Poetry 虚拟环境

这是大家最常问的点！有的时候咱们的VSCode可能没有找到poetry为我们创建的虚拟环境，导致货不对板。

方法 1：手动选择解释器（一次性）

按：

复制代码

Ctrl + Shift + P → "Python: Select Interpreter"

选择：

poetry env info --path可以校验出来你应该选哪一个Path的

复制代码

Poetry: /home/.../virtualenvs/xxx/bin/python

方法 2：让 Poetry 把 venv 放到项目内（超级自动）

bash 复制代码

poetry config virtualenvs.in-project true
poetry env remove $(poetry env list --full-path)
poetry install

项目根目录会出现 .venv/，VS Code 会自动识别。

📁 推荐的 Flask 项目结构（专业版）

虽然 demo 可以直接用 app.py，更推荐如下结构：

复制代码

flask-demo/
│
├── app/
│   ├── __init__.py
│   ├── routes.py
│   └── extensions.py
│
├── instance/
│   └── config.py
│
├── app.py
├── pyproject.toml
└── README.md

app/__init__.py：

python 复制代码

from flask import Flask

def create_app():
    app = Flask(__name__)

    from .routes import bp
    app.register_blueprint(bp)

    return app

app/routes.py：

python 复制代码

from flask import Blueprint

bp = Blueprint("main", __name__)

@bp.route("/")
def hello():
    return "Hello from blueprint!"

运行：

bash 复制代码

poetry run flask --app app:create_app --debug run

Reference📚 官方参考资料

Flask 官方快速开始（Quickstart）
https://flask.palletsprojects.com/en/latest/quickstart/
Flask CLI 用法
https://flask.palletsprojects.com/en/latest/cli/
Poetry 官方文档
https://python-poetry.org/docs/
VS Code Python 官方指南
https://code.visualstudio.com/docs/languages/python