每次看到有人把 MySQL 的连接信息直接写在 Flask 的app.py里我都替这个项目捏一把汗。这个写法在本地跑起来确实没问题但等你要部署到服务器、交接给同事、或者切换开发/测试环境时那一堆硬编码的用户名密码就是一颗定时炸弹。今天这篇就从最基础的“能用”写法讲起一步步把 Flask 配置 MySQL 连接信息这件事拆开揉碎讲清楚正确做法是什么、为什么是它、以及实际动手时怎么落地。这篇文章适合刚接触 Flask 后端开发、正在搭建自己的第一个带数据库项目的同学也适合已经写过几个 Flask 项目、但每次配置数据库都靠复制粘贴的老手。看完之后你会得到一个可以直接抄作业的配置方案以及一套遇到连接报错时快速定位问题的排查思路。1. 为什么“能跑就行”的连库方式坑了你1.1 最常见的三种“能用但坑人”写法先说最常见的三种写法大家可以对照一下自己有没有踩过。第一种直接用 PyMySQL 裸连。每次用数据就写一遍连接用完也不关闭连接代码一多数据库连接数直线飙升import pymysql app.route(/users) def users(): conn pymysql.connect( hostlocalhost, userroot, password123456, databasedemo ) cursor conn.cursor() cursor.execute(SELECT * FROM users) return str(cursor.fetchall())第二种用 Flask-SQLAlchemy 但配置写死在代码里app.config[SQLALCHEMY_DATABASE_URI] mysqlpymysql://root:123456127.0.0.1:3306/demo第三种写一个全局字典或者单独建一个database.py放连接参数然后一堆文件 import 这个字典。比前两种好一点但同样的问题是所有环境共用一套配置密码直接在代码仓库里裸奔。这些写法普遍存在三个问题敏感信息泄露。代码提交到 Git 之后数据库密码就永远留在历史记录里了。哪怕你后来删掉也已经在仓库里留下了痕迹。如果你是个人项目还好一旦是公司项目或者开源项目这就是安全事故。无法切换环境。开发环境、测试环境、生产环境的数据库地址、用户名、密码几乎都不一样。写死的配置意味着每次切换环境都要改代码、重启服务而且改的时候很容易把生产环境连接串弄坏。没有连接复用。数据库建立连接是个相对昂贵的操作需要 TCP握手、认证、分配资源。如果每次请求都新建连接、用完不关高并发下数据库服务器很快就会被连接数拖垮。这一点在 Flask 这种短生命周期请求的应用里尤其致命。1.2 最佳实践到底在解决什么问题我理解的“最佳实践”不是某个神奇框架而是一套解决问题的组合方案。它至少要解决三个层面的问题第一层安全数据库凭证不能出现在代码仓库里而是通过环境变量或配置文件注入生产环境用的是一套独立的强密码而不是开发时顺手敲的123456。第二层可维护代码里不出现任何环境相关的字面量。换数据库、换账号、换端口只需要改环境变量或.env文件代码本身零改动。第三层健壮性数据库连接必须经过连接池管理并且要处理连接失效、连接耗尽这些生产环境才容易出现的问题。这也是为什么很多 Flask 项目最后的配置形态都长得很像config.py里从环境变量读取参数拼连接串通过 Flask-SQLAlchemy 统一管理连接池。下面就从准备工作开始一步步搭建这套方案。2. 配置前的准备工作MySQL 侧与依赖侧2.1 确认 MySQL 版本与驱动选择动手之前先确认 MySQL 版本因为 5.7 和 8.0 在认证插件上差别挺大。MySQL 8.0 默认的认证插件是caching_sha2_password而 5.7 默认是mysql_native_password。这个差异直接影响 Python 驱动能不能连上后面讲 SSL 报错的时候会详细展开。Python 这边连接 MySQL 的主流驱动有三个选型可以参考这个表格驱动连接串 driver 名称优点缺点PyMySQLmysqlpymysql纯 Python 实现安装简单跨平台兼容好性能相对略低mysqlclientmysqlmysqldb性能好底层走 C 扩展老项目常用Windows 安装需要预编译包偶尔踩坑mysql-connector-pythonmysqlmysqlconnectorMySQL 官方维护和 SQLAlchemy 集成略粗糙我的建议是个人项目、快速开发、跨平台场景优先选 PyMySQL。生产环境如果追求极致性能再考虑 mysqlclient。原因很朴素——PyMySQL 只要pip install pymysql就完事了Windows、Linux、macOS 通吃不折腾。2.2 用虚拟环境隔离 Flask 依赖强烈建议不要在系统 Python 环境里直接装 Flask 和数据库驱动。不同项目的依赖容易冲突而且系统 Python 环境被装得乱七八糟之后排查问题会非常痛苦。用虚拟环境隔离每个项目一套依赖互不干扰。创建并激活虚拟环境的命令python3 -m venv venv source venv/bin/activate # Windows 下用 venv\Scripts\activate然后安装核心依赖pip install flask pip install flask-sqlalchemy pip install pymysql pip install python-dotenv pip install cryptography # 预估会用到 caching_sha2_password 认证时提前装上装完后把依赖列表导出到requirements.txt方便其他人复现环境pip freeze requirements.txt2.3 建库建用户的最小权限原则在 MySQL 侧我不建议直接用 root 账号连应用数据库。应用只需要对自己的业务库执行增删改查给了 root 权限等于给了整个数据库实例的钥匙。最小权限原则的意思是应用账号只有它需要的那几个权限其他一概不给。先在 MySQL 客户端里创建业务库CREATE DATABASE flask_demo CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;创建应用专用用户并授权CREATE USER flask_app% IDENTIFIED BY 这里写一个真正强壮的密码; GRANT SELECT, INSERT, UPDATE, DELETE ON flask_demo.* TO flask_app%; FLUSH PRIVILEGES;关于flask_app%里的%意思是允许从任意主机连接。如果应用和数据库在同一台机器上写成flask_applocalhost会更安全如果数据库独立部署就按实际应用服务器 IP 设置白名单。数据库名、用户名、密码、主机、端口这些信息接下来全部通过环境变量传给 Flask不写在代码里。3. 连接信息的正确存放方式从硬编码到环境变量3.1 config.py 配置类的设计Flask 官方推荐的做法是用app.config对象管理配置而配置内容最好通过config.py里的配置类来组织。我的习惯是写一个Config基类里面定义默认值再根据环境继承出不同的子类。# config.py import os from urllib.parse import quote_plus class Config: SECRET_KEY os.environ.get(SECRET_KEY) or dev-secret-change-me SQLALCHEMY_TRACK_MODIFICATIONS False SQLALCHEMY_ENGINE_OPTIONS { pool_size: 10, # 连接池保持的连接数 max_overflow: 5, # 峰值时额外创建的上限 pool_timeout: 30, # 获取连接的超时时间 pool_recycle: 3600, # 连接回收周期 pool_pre_ping: True, # 使用前先探活 } DB_USER os.environ.get(DB_USER, flask_app) DB_PASSWORD os.environ.get(DB_PASSWORD, ) DB_HOST os.environ.get(DB_HOST, 127.0.0.1) DB_PORT os.environ.get(DB_PORT, 3306) DB_NAME os.environ.get(DB_NAME, flask_demo) property def SQLALCHEMY_DATABASE_URI(self): return ( fmysqlpymysql://{self.DB_USER}:{quote_plus(self.DB_PASSWORD)} f{self.DB_HOST}:{self.DB_PORT}/{self.DB_NAME}?charsetutf8mb4 ) class DevelopmentConfig(Config): DEBUG True class ProductionConfig(Config): DEBUG False这里有个细节值得说DB_PASSWORD拼进连接串之前用quote_plus()做了 URL 编码。原因是连接串本质是一个 URL密码里如果含、#、%、/这些特殊字符不编码会把整条连接串解析错。后面常见问题里会有实际案例。SQLALCHEMY_ENGINE_OPTIONS这个配置是 Flask-SQLAlchemy 3.x 版本推荐的写法旧版的SQLALCHEMY_POOL_SIZE、SQLALCHEMY_POOL_RECYCLE、SQLALCHEMY_POOL_PRE_PING这些参数在 3.x 里已经被移除了不再生效。如果你在网上看到老教程配置对不上是正常的优先用SQLALCHEMY_ENGINE_OPTIONS这种新格式。3.2 .env 文件与读取环境变量的细节环境变量在 Linux 终端里可以用export设置Windows PowerShell 里可以用$env:VARvalue设置但每次部署都要敲一遍很麻烦。更实用的做法是把环境变量写进.env文件用python-dotenv在应用启动时自动加载。项目根目录创建.env文件SECRET_KEYyour-secret-key-here DB_USERflask_app DB_PASSWORD你的强密码 DB_HOST127.0.0.1 DB_PORT3306 DB_NAMEflask_demo然后在config.py顶部加载.envfrom dotenv import load_dotenv load_dotenv() # 默认读取当前工作目录下的 .env写.env时有两个容易踩的坑。第一个是路径问题Flask 启动方式不同当前工作目录可能不一样。稳妥的做法是在config.py里用os.path.abspath(os.path.dirname(__file__))拿到文件所在目录再指定.env的绝对位置。第二个是.env文件一定不能提交进 Git。在.gitignore里加上.env但仓库里要保留一个.env.example让别人知道需要配置哪些字段只不过里面填的是占位符而不是真实密码。3.3 不同环境开发/测试/生产的配置切换配置类设计好了还需要在应用入口里根据环境变量决定加载哪个配置。我的写法是这样# app.py import os from flask import Flask from config import DevelopmentConfig, ProductionConfig def create_app(): app Flask(__name__) env os.environ.get(FLASK_ENV, development) if env production: app.config.from_object(ProductionConfig) else: app.config.from_object(DevelopmentConfig) return app启动生产环境时先设置环境变量再启动export FLASK_ENVproduction export SECRET_KEY生产环境的key export DB_PASSWORD生产数据库密码 flask run这样做的核心好处是代码里不存在环境差异切换环境只是改变环境变量。本地调试用开发配置上生产用生产配置两个环境之间天然隔离。4. SQLAlchemy 连接串与连接池参数实战4.1 连接串的完整格式与编码问题完整的 SQLAlchemy MySQL 连接串格式是这样的mysqlpymysql://用户名:密码主机地址:端口/数据库名?charsetutf8mb4拆开来看mysqlpymysql表示用 PyMySQL 作为底层驱动用户名:密码对应数据库账号信息主机地址:端口是 MySQL 服务地址默认 3306/数据库名是要连接的数据库?charsetutf8mb4是连接级字符集配置这里我特别强调charsetutf8mb4是因为utf8在 MySQL 里其实对应的是utf8mb3最多只能存 3 字节的字符像 Emoji 这类 4 字节字符就存不进去。统一用utf8mb4可以避免很多字符集相关的坑。如果密码里含有特殊字符不能用原始的密码字符串直接拼连接串否则连接串会被截断或者解析错误。用urllib.parse.quote_plus编码之后特殊字符会被转换成 URL 安全的格式from urllib.parse import quote_plus safe_password quote_plus(你的密码) # 假设密码是 abc123结果是 abc%401234.2 连接池关键参数pool_size、pool_recycle、pool_pre_pingSQLAlchemy 的create_engine()默认开启连接池但默认参数并不一定适合生产环境。Flask-SQLAlchemy 里通过SQLALCHEMY_ENGINE_OPTIONS配置连接池参数SQLALCHEMY_ENGINE_OPTIONS { pool_size: 10, max_overflow: 5, pool_timeout: 30, pool_recycle: 3600, pool_pre_ping: True, }逐项说明我的理解pool_size10连接池始终保持 10 个数据库连接Application 启动时并不会全部建立而是按需创建并保留。并发请求优先复用空闲连接没有空闲连接且池未满时才新建。选多大的值要看业务量一般 Web 应用 10 到 20 够用。max_overflow5连接池满了之后峰值流量下最多可以额外创建多少个连接。超过这个数量之后新的请求只能等待空余连接。这个值不宜过大否则瞬间流量会把数据库打挂。pool_timeout30没有空闲连接时的等待秒数超过就抛TimeoutError。如果服务经常报这个异常说明连接池不够用优先排查是不是连接没释放而不是盲目加大 pool_size。pool_recycle3600MySQL 服务器有个wait_timeout参数默认 28800 秒8 小时超过这个时间没有活动的连接会被服务端强制关闭。如果连接池里的连接恰好被关掉了客户端不知道下次请求就会报MySQL server has gone away。pool_recycle的作用是让连接池在到达指定时长后主动丢弃旧连接、建立新连接从而避开服务端的超时回收。设置的数值要小于wait_timeout我这里用 3600 秒。pool_pre_pingTrue每次从连接池拿连接之前发一条探测指令SELECT 1确认连接真的可用。不可用就丢弃重建。这个参数能非常有效地避免断连问题代价是每次请求多一条极轻量的探测查询。4.3 常见 SSL 连接错误的排查MySQL 8.0 默认启用了 SSL导致一部分人在第一次连接时会遇到奇奇怪怪的报错。比较常见的是这两类第一类报错是RuntimeError: cryptography package is required for sha256_password or caching_sha2_password auth methods这个报错的意思是服务器使用caching_sha2_password认证插件但 PyMySQL 做这个认证需要cryptography库当前环境没装。解决方案很简单装一下就好pip install cryptography第二类是和 SSL 握手相关的报错比如pymysql.err.OperationalError: (2026, SSL connection error: SSL_CTX_set_min_proto_version error)这个通常是服务端 SSL 配置和 PyMySQL 的 SSL 默认行为不兼容导致的。如果你的 MySQL 部署在内网应用和数据库之间的网络环境可控可以在连接串里显式关闭 SSLSQLALCHEMY_DATABASE_URI ( fmysqlpymysql://{DB_USER}:{quote_plus(DB_PASSWORD)} f{DB_HOST}:{DB_PORT}/{DB_NAME}?charsetutf8mb4ssl_disabledtrue )如果公司安全策略要求数据库连接必须启用 SSL那就不要用ssl_disabledtrue而是按 MySQL 服务端提供的 CA 证书配置ssl_ca。具体配置方式看 MySQL 服务端怎么签发的证书不要为了省事随便关 SSL尤其在公网环境下。5. 常见问题速查表与排查实录5.1 认证类错误Access denied、Unknown database、Host 限制这部分我把平时最常遇到的报错和排查方向整理成了一张表报错信息原因解决Access denied for user xxxhost (using password: YES)用户名不存在、密码错误、或用户不允许从该主机连接用正确的账号密码在 MySQL 客户端测试检查用户权限表里host是否包含当前来源地址Unknown database flask_demo数据库不存在或者名字拼错在 MySQL 客户端执行SHOW DATABASES;确认库名Host 1.2.3.4 is not allowed to connect to this MySQL server用户授权里host字段不允许当前来源 IP用GRANT ... TO user具体IP或者%授权然后FLUSH PRIVILEGES有个小技巧遇到Access denied时先用 MySQL 命令行工具手动试一下连接如果命令行能连上说明问题在应用侧的账号密码配置命令行也连不上说明是数据库侧的用户权限问题。这一步能快速缩小排查范围。5.2 特殊字符密码导致的连接失败我接过一次很典型的排查求助对方说密码明明没问题MySQL 命令行也能连但 Flask 里就是报Access denied。一看代码密码是password123直接拼进连接串变成了mysqlpymysql://flask_app:password123127.0.0.1:3306/flask_demoURL 解析的时候被当成了账号密码部分的结束符实际密码变成了pass后面word123127.0.0.1被当成主机地址的一部分整个连接串被拆碎了。解决方式就是用quote_plus编码密码再拼连接串。所以我在config.py里特意放了这个处理就是为了防止这种看似玄学的连接失败。5.3 长连接失效与连接池耗尽数据库连接是长连接MySQL 默认配置下持续 8 小时没有请求的连接会被服务端断开。这种问题在高频访问的白天反而不容易暴露一旦到了凌晨流量低谷早晨第一批请求就会撞上已经失效的连接。典型报错OperationalError: (2006, MySQL server has gone away)解决思路是双保险pool_recycle3600定期回收旧连接pool_pre_pingTrue在使用前探活。前者降低了拿到失效连接的概率后者确保就算拿到了也能立刻发现并重建。还有一种情况是并发突然上去之后报QueuePool limit of size 10 overflow 5 reached, connection timed out这说明连接池不够用了。先确认是不是每条请求都正确关闭了连接Flask-SQLAlchemy 的 Session 在请求结束后如果没清理连接会一直占着不还。再看是不是某个慢查询把连接占得太久最后才考虑调大 pool_size。5.4 中文乱码与字符集不一致问题中文存进数据库变成问号一般有三个层面的字符集需要保持一致数据库本身、数据表、应用连接串。数据库初始化时用utf8mb4CREATE DATABASE flask_demo CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;建表时也指定utf8mb4CREATE TABLE users ( id INT PRIMARY KEY AUTO_INCREMENT, name VARCHAR(100) ) DEFAULT CHARSETutf8mb4 COLLATEutf8mb4_unicode_ci;应用连接串带?charsetutf8mb4。三层统一用utf8mb4基本不会再出现乱码问题。如果数据库已经建好了用SHOW CREATE TABLE users;检查一下表结构然后ALTER TABLE转换字符集。6. 最后再分享一个我踩过的坑前阵子接手一个旧项目requirements.txt里同时锁了pymysql和mysqlclient两个驱动。连接串写的是mysqlpymysql://...按说应该用 PyMySQL但程序启动后 SQLAlchemy 报了驱动冲突相关的模糊错误排查了半天才发现是依赖里另一个库隐式加载了mysqldb驱动把连接串指定的驱动给覆盖了。从那以后我的习惯是一个 Flask 项目里只保留一个 MySQL 驱动requirements.txt里明确锁定版本。如果项目历史遗留了多个驱动先清理掉不用的那个再跑一遍核心链路测试。这类问题不是必现的但一旦被触发排查成本远高于一开始就保持依赖干净。另外说一个很实际的经验连接配置写完先写一个最小脚本验证create_engine(...).connect()能成功再跑 Flask 应用。这个 30 秒的验证能帮你把“Flask 问题”和“数据库连接问题”彻底隔离开。这套方案我用了很多年从个人博客到小团队的生产项目都验证过。核心思路其实就是三句话配置走环境变量、连接交给连接池管理、账号权限按最小化来。你按这个思路重构一次自己的 Flask 项目数据库连接这块基本就不会再出幺蛾子了。