Gmail API代码运行正常，PyInstaller打包为exe报UnknownApiNameOrVersion错误

报错根因 #

这个UnknownApiNameOrVersion报错是PyInstaller打包的典型适配问题，并非Gmail调用代码本身的逻辑错误：

• PyInstaller默认的静态代码分析，不会自动识别googleapiclient动态加载的子模块、以及内置的静态接口定义缓存文件
• 打包后的程序在调用build函数时，既没法本地匹配到Gmail v1的接口描述文件，又因为打包环境的网络/路径问题拉取在线发现文档失败，最终抛出接口名/版本找不到的错误。

可直接落地的解决方法 #

方法1：全量收集依赖资源后重新打包 #

这是改动量最小的方案，直接在你原本的PyInstaller打包命令里追加以下参数，强制把Google API相关包的所有依赖全部打入exe：

pyinstaller 你原有的所有参数（比如--onefile --windowed等） ^
  --collect-all googleapiclient ^
  --collect-all google_auth_oauthlib ^
  --hidden-import googleapiclient.discovery ^
  --hidden-import google_auth_httplib2

• --collect-all的作用是跳过PyInstaller的默认筛选，把对应安装包里的所有代码、数据文件、动态加载模块全部打包进去，不会遗漏运行时需要的接口定义资源。

方法2：使用本地静态发现文档（稳定性最高） #

适合网络环境不稳定、需要离线运行的分发场景，完全绕开运行时拉取在线接口文档的逻辑：

1. 在能正常运行代码的开发环境里，提前生成Gmail v1的本地接口定义文件：

   from googleapiclient.discovery import build
   # 拉取一次官方的接口描述文档
   service = build('gmail', 'v1', static_discovery=False)
   # 把文档内容存成本地json文件
   with open('gmail_v1_discovery.json', 'w', encoding='utf-8') as f:
       f.write(service._rootDesc.to_json())
   

2. 修改你原来的build方法调用逻辑，读本地存储的接口定义文件，同时适配PyInstaller打包后的临时资源路径：

   import sys
   def get_packaged_resource_path(filename):
       # 兼容PyInstaller打包后的临时解压路径
       if hasattr(sys, '_MEIPASS'):
           return os.path.join(sys._MEIPASS, filename)
       # 兼容开发环境直接运行py的场景
       return os.path.join(os.path.abspath("."), filename)
   
   # 原来的build调用替换为以下逻辑
   with open(get_packaged_resource_path('gmail_v1_discovery.json'), 'r', encoding='utf-8') as f:
       discovery_doc_content = f.read()
   service = build(serviceName='gmail',
                   version='v1',
                   credentials=creds,
                   static_discovery=False,
                   discoveryServiceUrl=discovery_doc_content)
   

3. 打包时通过--add-data参数把这个json文件打入exe包：
   • Windows系统打包用：--add-data "gmail_v1_discovery.json;."
   • Mac/Linux系统打包用：--add-data "gmail_v1_discovery.json:."

额外避坑提示 #

• 所有你代码里用到的本地配置文件（client_id.json、token.json），都要用上面的get_packaged_resource_path方法处理路径，不要直接写相对路径，不然打包后运行时会因为工作目录变化找不到文件，触发认证报错。
• 不要使用0.12.0版本以下的google-api-python-client，旧版本和PyInstaller有已知的适配冲突，升级到最新稳定版再打包。
• 如果运行时拉取在线发现文档超时，可以把static_discovery参数设为True，优先使用包内置的本地缓存，不要每次运行都拉取远程内容。

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