GCP App Engine部署Flask连接Cloud SQL出现2003连接被拒错误

你遇到的(2003, "Can't connect to MySQL server on 'localhost' ([Errno 111] Connection refused)")报错，本质是连接请求没有走到Cloud SQL的unix socket，而是回退尝试连接本地3306端口被拒绝，按以下顺序逐一排查即可：

1. 校验连接字符串配置 #

• 确认连接串里的connection_name替换为Cloud SQL实例的完整实例连接名，格式为项目ID:实例所在区域:实例ID，不要填实例的显示昵称，填错会直接导致socket路径无效。
• 注意：连接串中禁止手动添加host=localhost参数，该参数优先级高于unix_socket配置，会强制走本地TCP连接触发报错
• 正确的连接串格式参考：

# 替换对应占位符即可，注意@后直接跟/加数据库名，不要写host
databaseUri = 'mysql+pymysql://<数据库用户名>:<数据库密码>@/<数据库名>?unix_socket=/cloudsql/<完整实例连接名>'

• 数据库用户名、密码、库名如果包含特殊字符，需要做URL编码，避免解析失败导致配置失效。

2. 补全App Engine部署配置（最高发漏配项） #

仅开启Cloud SQL Administrator API不足以建立连接，必须在部署配置文件app.yaml中声明需要关联的Cloud SQL实例，App Engine才会在运行容器时自动将Cloud SQL的unix socket挂载到/cloudsql/路径下。如果漏了该配置，路径下找不到对应socket文件，pymysql会自动回退尝试连接本地3306端口，正好匹配你看到的报错。
需要在app.yaml根层级添加以下配置：

beta_settings:
  cloud_sql_instances: <你的完整Cloud SQL实例连接名>

• 如果使用App Engine柔性环境，还需要给App Engine默认服务账号（格式为<你的项目ID>@appspot.gserviceaccount.com）绑定Cloud SQL Client角色，没有该角色即使挂载了socket也会被权限拦截。

3. 校验依赖与代码逻辑 #

• 确认requirements.txt中已经声明pymysql、sqlalchemy（使用Flask-SQLAlchemy则同步声明）依赖，部署时会自动安装，缺少pymysql会导致unix_socket连接逻辑不生效。
• 检查代码中的配置加载逻辑，确认生产环境下Flask实际读取的数据库URI就是你配置的Cloud SQL连接串，没有被本地开发环境的localhost默认配置覆盖，也没有硬编码其他本地连接逻辑。

4. 连通性校验 #

部署完成后通过App Engine内置日志查看连接行为：

• 如果日志显示连接目标为/cloudsql/开头的socket路径，说明配置已生效，此时仍连接失败则检查Cloud SQL侧的用户授权（建议对应用户设置允许所有host连接，即host值为%）、实例运行状态是否正常。
• 如果日志仍显示尝试连接127.0.0.1:3306，说明数据库配置没有被正确加载，重点排查环境变量注入、多环境配置切换逻辑。

常见踩坑：本地开发时写死了localhost连接配置，部署时没有切换到生产配置，或者环境变量名拼写错误，导致代码读取到的数据库URI根本不是你配置的Cloud SQL地址。

内容的提问来源于stack exchange，提问作者Agares