psycopg2安装失败或导入报错的根源是未区分binary版与源码版，开发用psycopg2-binary，生产有依赖时可用psycopg2；URI需用postgresql+psycopg2://前缀、密码URL编码、端口显式写出；Flask中db须init_app后使用，session须正确关闭防连接池耗尽。
psycopg2 安装失败或导入报错
常见现象是 ImportError: No module named psycopg2 或 ModuleNotFoundError: No module named 'psycopg2'，尤其在 macOS 或 Windows 上。根本原因不是没装，而是没装对——psycopg2 有纯 Python 的 psycopg2-binary 和需编译的源码版 psycopg2 之分。
- 开发阶段直接用
pip install psycopg2-binary，省去编译依赖（如 gcc、postgresql-client-dev） - 生产环境若已有 PostgreSQL 开发包，可选
pip install psycopg2，体积更小、略快一点 - Mac M1/M2 用户如果遇到
ld: library not found for -lpq，先确认已装brew install libpq，再设环境变量：export PATH="/opt/homebrew/opt/libpq/bin:$PATH" - Windows 用户避免直接
pip install psycopg2，优先用psycopg2-binary，否则大概率卡在编译环节
SQLALCHEMY_DATABASE_URI 格式写错
URI 写错会导致 Flask 启动时无报错但后续操作全崩，比如 sqlalchemy.exc.OperationalError: (psycopg2.OperationalError) FATAL: database "xxx" does not exist，其实只是数据库名拼错了，或者端口漏了。
- 标准格式是：
postgresql+psycopg2://: @ : / - 本地默认端口 5432 可省略，但显式写出更稳妥（尤其 Docker 场景）：
postgresql+psycopg2://postgres:pass@localhost:5432/myapp - 密码含特殊字符（如
@、/、:）必须 URL 编码，例如密码是ab@c/d→ab%40c%2Fd，否则解析会截断 - 别用
postgres://前缀——SQLAlchemy 1.4+ 已弃用，强制用postgresql://或postgresql+psycopg2://，否则可能静默降级为旧驱动或连接失败
Flask 初始化时没配好 SQLAlchemy 实例
常见错误是直接在模块顶层创建 db = SQLAlchemy()，但没绑定 app，导致视图里调 db.session.add() 报 RuntimeError: Application not registered on db instance。
- 正确做法：先实例化不带 app 的
db = SQLAlchemy()，再在创建 Flask app 后调用db.init_app(app) - 别在
create_app()外提前调db.create_all()，它依赖 app context，应放在with app.app_context(): db.create_all()里 - 如果用了工厂模式，确保所有模型定义在
db实例化之后、init_app()之前完成导入，否则create_all()找不到表 - 调试时可临时加一句
print(db.engine.url)确认 URI 是否被正确解析（注意：只在app.app_context()内有效）
连接池耗尽或超时没释放
线上跑一阵后出现 sqlalchemy.exc.TimeoutError: QueuePool limit of size 5 overflow 10 reached，本质是 session 没关、连接没归还，不是配置太小。
- Flask-SQLAlchemy 默认启用连接池（
pool_size=5,max_overflow=10），够小项目用，但别盲目调大——治标不治本 - 每个请求结束前必须关闭 session：Flask-SQLAlchemy 会自动在请求上下文退出时清理，前提是没手动调
db.session.remove()或重复db.session = ... - 长任务（如 Celery）里用
db.session，必须显式db.session.close()或用with db.session.begin():确保事务边界清晰 - 检查有没有忘写
db.session.commit()或db.session.rollback()导致 session 卡在 pending 状态，这种问题不会立刻报错，但会慢慢吃光连接
URI 里的密码编码、驱动前缀、session 生命周期这三处，改起来就几行，但漏掉一个，调试时容易绕进网络配置或 PostgreSQL 权限的坑里。
