不同设备运行GSpread代码报expected_headers非唯一异常

用于操作Google表格的Python代码如下：

import gspread
from oauth2client.service_account import ServiceAccountCredentials
import pandas as pd


scope = [
'https://www.googleapis.com/auth/spreadsheets',
'https://www.googleapis.com/auth/drive'
]

credentials=ServiceAccountCredentials.from_json_keyfile_name('keyfile.json',scope)

gc= gspread.authorize(credentials)
sh= gc.open('Spreadsheet') 

worksheet = sh.worksheet(sheetName)
dataframe = pd.DataFrame(worksheet.get_all_values())

• 同一份代码在个人MacBook上可正常运行，同事的MacBook执行时抛出异常：GSpreadException: the given 'expected_headers' are not uniques
• 排查确认异常触发时get_all_values()方法无法正确加载电子表格内容，所有列头被识别为重复值，但目标工作表内实际存在有效内容
• 初步判断为依赖版本差异导致跨设备运行结果不一致，需确认根因与修复方案

这个异常的核心诱因确实是gspread库的版本不一致：

• 你本地设备安装的是5.0.0以下的旧版本gspread，旧版本既不会对读取到的表头做唯一性校验，也会自动裁剪工作表末尾无内容的空行、空列，即使首行存在空值也能正常返回数据。
• 同事设备安装的是5.0.0及以上的新版本gspread，该版本两个逻辑变化直接触发异常：
  • 新增表头唯一性校验规则，读取数据时如果首行存在空单元格，会自动给空表头填充统一的占位值，直接抛出重复表头的报错
  • 调整了工作表有效边界的判定逻辑，如果工作表存在曾编辑过又清空内容的"幽灵单元格"（Google Sheets会保留这类单元格的格式记录，将其判定为有效范围边界），get_all_values()会把这些空行、空列全部纳入返回结果。你排查时看到的方法加载内容异常、列头全是重复值，就是因为返回结果里包含了大量空列，首行对应空列的位置全为空值，被校验逻辑判定为重复表头。

按优先级从高到低可选择以下方案修复：

• 统一依赖版本：这是成本最低的修复方式。先在你自己正常运行代码的设备上执行pip show gspread查询本地安装的gspread版本号，再在同事设备上执行pip install gspread==<查询到的版本号>安装完全一致的版本，即可保证两端运行逻辑一致。
• 显式指定读取范围：如果要适配新版本gspread，放弃get_all_values()的自动范围判定，直接根据表格实际有效数据范围传入固定区间读取，比如有效数据在A1到F200的区域，就将代码替换为worksheet.get_values('A1:F200')，从根源上避免读到空列空行。
• 增加空值过滤逻辑：如果需要保留get_all_values()的自动读取能力，可以在读取后手动过滤全空的行和列，再转换为DataFrame，参考代码如下：

all_values = worksheet.get_all_values()
# 过滤全空行
non_empty_rows = [row for row in all_values if any(cell.strip() for cell in row)]
# 计算有效列边界，裁剪尾部全空列
def get_row_valid_length(row):
    for idx in range(len(row)-1, -1, -1):
        if row[idx].strip() != '':
            return idx + 1
    return 0
max_valid_col = max(get_row_valid_length(row) for row in non_empty_rows)
cleaned_values = [row[:max_valid_col] for row in non_empty_rows]
# 转换为DataFrame，第一行为表头
dataframe = pd.DataFrame(cleaned_values[1:], columns=cleaned_values[0])

• 长期优化建议：当前代码使用的oauth2client库已经停止维护多年，长期使用建议替换为gspread官方推荐的google-auth认证库，避免后续出现其他兼容性问题。

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