VS Code 调试器每次启动都会创建新 shell，导致手动 set 的环境变量无法传递给调试进程；需通过 launch.json 配置 env 字段或使用 .env 文件实现可靠加载。

vs code 调试器每次启动都会创建新 shell，导致手动 `set` 的环境变量无法传递给调试进程；需通过 `launch.json` 配置 `env` 字段或使用 `.env` 文件实现可靠加载。

在 VS Code 中开发 Flask 应用时，常误以为在集成终端中执行 set FLASK_ENV=development 就能让调试器读取该变量——但这是无效的。原因在于：VS Code 的调试会话（Debug Session）并不复用你当前终端的环境，而是启动一个全新的、隔离的 shell 进程，因此你在终端中设置的变量对调试器完全不可见。

✅ 正确做法一：配置 launch.json（推荐）

在项目根目录下创建或编辑 .vscode/launch.json，显式声明环境变量：

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Python: Flask",
      "type": "python",
      "request": "launch",
      "module": "flask",
      "args": [
        "--app",
        "run:app",
        "--debug",
        "--port",
        "5000"
      ],
      "env": {
        "FLASK_ENV": "development",
        "FLASK_APP": "run.py",
        "SQLALCHEMY_DATABASE_URI": "sqlite:///dev.db"
      },
      "justMyCode": true
    }
  ]
}

⚠️ 注意：FLASK_ENV 在 Flask 2.2+ 已被弃用（仅保留兼容性），建议改用 FLASK_DEBUG=1 + FLASK_ENV=development（或直接依赖 FLASK_DEBUG），并在代码中统一通过 os.environ.get('FLASK_ENV', 'production') 兜底。

✅ 正确做法二：使用 .env 文件（更简洁、可版本控制）

安装 python-dotenv：

VS Code Node

通过作为 OpenClaw 节点连接的 VS Code/Cursor IDE 操作代码，提供 40 多种命令，涵盖文件操作、语言智能、Git、测试等功能。

下载

pip install python-dotenv

在项目根目录（与 run.py 同级）创建 .env 文件：

FLASK_ENV=development
FLASK_APP=run.py
SQLALCHEMY_DATABASE_URI=sqlite:///dev.db

然后在 run.py 开头添加自动加载逻辑（必须放在 create_app() 调用前）：

from flask import Flask
import os
from dotenv import load_dotenv

# 加载 .env 文件（自动查找当前目录及父目录中的 .env）
load_dotenv()

print(f"FLASK_ENV: {os.environ.get('FLASK_ENV')}")  # 确认已加载

from app import create_app

app = create_app()

? 验证是否生效

运行调试后，检查控制台输出是否显示 FLASK_ENV: development；同时确认 app.config 是否正确加载了 DevelopmentConfig 中的 SQLALCHEMY_DATABASE_URI —— 这是解决 RuntimeError: Either 'SQLALCHEMY_DATABASE_URI' or 'SQLALCHEMY_BINDS' must be set. 的关键。

? 补充说明

• ❌ 不要依赖终端 set / export 命令配合 Debug 模式，它只影响当前终端 Shell，不继承至调试子进程；
• ✅ 终端命令仍可用于非调试场景（如 python -m flask run），此时需确保在运行前已 export 变量；
• ? 生产部署时，应通过系统级环境变量或容器编排工具（如 Docker 的 env_file）管理，而非 .env 文件（避免敏感信息泄露）。

通过以上任一方式，即可确保 VS Code 调试器稳定读取环境变量，使 Flask 应用按预期加载开发、测试或生产配置。