GitHub Actions运行Python脚本imaplib报NoneType无replace属性错误

问题结论 #

该错误和imap-tools依赖无关，不需要更换依赖，报错的根本原因是GitHub Actions运行环境中缺少邮箱账号、密码对应的环境变量，导致代码读取到空值传入登录方法触发异常。

报错原理说明 #

调用栈显示imaplib内置库的_quote方法处理登录参数时调用了replace方法，你传入的邮箱账号或密码是None值，没有replace属性才触发报错。你本地测试时依赖项目根目录的.env文件读取环境变量，但是GitHub Actions运行时默认不会加载这个文件，也不会自动注入你没配置的私密变量，所以os.getenv读取到的两个参数都是空值。

解决步骤 #

• 第一步：在GitHub仓库配置私密变量
  进入对应仓库的Settings页面，在左侧菜单栏找到Secrets and variables→Actions，点击New repository secret分别添加两个变量：
  • 变量名FROM_EMAIL，值为你的登录邮箱地址
  • 变量名FROM_PWD，值为你的邮箱登录密码（如果是Gmail需要使用应用专用密码，不能使用账号主密码）
• 第二步：修改Workflow配置注入环境变量
  调整main.yml中执行Python脚本的步骤，把配置好的Secrets注入到运行时环境：

  - name: Execute Python script # Run the app.py
    env:
      FROM_EMAIL: ${{ secrets.FROM_EMAIL }}
      FROM_PWD: ${{ secrets.FROM_PWD }}
    run: python app.py
  

• 可选：添加空值校验避免同类问题
  可以在read_email.py的mail_connect方法中增加参数校验逻辑，提前暴露配置问题：

  def mail_connect():
      load_dotenv()
      FROM_EMAIL = getenv('FROM_EMAIL')
      FROM_PWD = getenv('FROM_PWD')
      # 新增校验逻辑
      if not FROM_EMAIL or not FROM_PWD:
          raise RuntimeError("未读取到邮箱账号或密码环境变量，请检查配置")
      SMTP_SERVER = "imap.gmail.com"
  
      mailbox = MailBox(SMTP_SERVER).login(
          FROM_EMAIL, FROM_PWD, initial_folder='INBOX')
  
      read_email(mailbox)
  

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