连接Cloud SQL时出现KeyError错误该如何解决？

核心问题分析 #

你遇到的KeyError: '--connection_name_here--'本质是Python无法从系统环境变量中找到对应键名的变量，和Cloud SQL的连接名称本身、IP设置无关，重点排查环境变量和代码中键名的匹配问题。

可能的原因及解决步骤 #

• 环境变量未定义或拼写错误
  代码中os.environ[self.keys["gProj"]]是通过键名读取环境变量，但你要么根本没在系统/运行环境中设置这个变量，要么变量名和代码里的键名不匹配。
  解决：

  1. 先打印self.keys["gProj"]的具体值，确认它对应的环境变量名是什么（比如在代码开头加print(self.keys["gProj"])）。
  2. 检查系统/运行环境中是否存在这个名称的环境变量：
     • Windows：打开命令行输入echo %变量名%，看是否能输出正确的连接名。
     • Linux/macOS：终端输入echo $变量名验证。
  3. 如果变量不存在，手动添加对应环境变量，确保值是你的Cloud SQL实例连接名（格式project:region:instance）。

• self.keys字典的键值不匹配
  你代码里的self.keys["gProj"]对应的字符串（也就是报错里的--connection_name_here--），并不是你实际设置的环境变量名。比如你设置的环境变量叫INSTANCE_CONN_NAME，但self.keys["gProj"]存的却是错误的键名。
  解决：检查self.keys字典中"gProj"对应的value，确保和你设置的环境变量名称完全一致（注意Linux/macOS环境变量区分大小写）。

• 环境变量未生效
  如果你是在终端临时设置的环境变量（比如Windows用set 变量名=值，Linux用export 变量名=值），但运行代码的IDE/终端没有重启，导致新设置的变量没被读取到。
  解决：重启IDE或运行代码的终端，或者直接在IDE的运行配置中手动添加所需的环境变量。

快速验证方法 #

可以先把代码中的环境变量读取部分改成硬编码，排除环境变量的问题：

instance_connection_name = "你的实例连接名"  # 比如"my-project:us-central1:my-instance"
db_user = "你的数据库用户名"
db_pass = "你的数据库密码"
db_name = "你的数据库名称"

如果这样能成功连接，就可以确定问题出在环境变量或self.keys的配置上。

内容的提问来源于stack exchange，提问作者Alarm-1202