df2gspread.upload()静默失败，PyCharm运行正常却无法导出数据至Google Sheets

核心故障原因 #

• 服务账号无目标表格编辑权限：Google Sheets默认仅创建者可编辑，你使用的服务账号邮箱未被添加为表格的共享编辑用户，服务账号无写入权限，部分版本的df2gspread不会抛出权限类报错。
• spreadsheet_key填写错误：表格ID提取错误，正确ID为浏览器地址栏https://docs.google.com/spreadsheets/d/后、/edit前的字符串，多复制/少复制字符都会导致无法定位到目标表格。
• 工作表名称不匹配：wks_name参数填写的工作表名称和目标表格里的实际名称不一致，包括大小写、空格、特殊字符差异，或者对应工作表不存在。
• Google Cloud API未开启：你的Google Cloud项目没有提前开启Google Sheets API和Google Drive API，接口调用被官方拦截，部分旧版本依赖库不会返回明确报错。
• 依赖库版本不兼容：df2gspread已停止维护多年，和新版本的gspread、oauth2client存在兼容性问题，会出现无报错但写入无响应的情况。
• 网络连通性异常：本地运行环境无法正常访问Google服务，接口请求超时，部分版本的依赖库不会抛出明确的超时报错。

可行解决方法 #

• 授权服务账号权限：打开你的凭证JSON文件，复制client_email字段对应的邮箱地址，打开目标Google Sheets，点击右上角「共享」，粘贴邮箱、选择「编辑者」权限后确认。注意：如果表格设置了区域保护，需要把服务账号加到可编辑区域的白名单中
• 校验表格ID和工作表名称：重新提取复制spreadsheet_key，核对目标表格中工作表的实际名称，和wks_name参数完全保持一致。
• 开启对应API：进入你的Google Cloud项目控制台，分别搜索Google Sheets API、Google Drive API，点击「启用」即可。
• 替换写入逻辑弃用df2gspread：直接使用gspread官方提供的方法写入数据，兼容稳定性更高，参考代码如下：

# 替换原有d2g.upload部分的代码即可，和原有row_names=True效果一致
sh = gc.open_by_key(spreadsheet_key)
worksheet = sh.worksheet(wks_name)
# 把行索引转为普通列保留行名
df = df.reset_index()
worksheet.update([df.columns.values.tolist()] + df.values.tolist())

• 降低依赖库版本：如果要继续使用df2gspread，可以安装匹配的旧版本：pip install gspread==3.7.0 df2gspread==1.0.4 oauth2client==4.1.3
• 排查网络连通性：确认本地运行环境可以正常访问Google相关服务，或配置符合要求的代理即可。

内容的提问来源于stack exchange，提问作者Elçin Sayin