Flask-Mail报KeyError错误：环境变量未配置致邮件服务启动失败

问题背景 #

创建可发送确认邮件的Flask服务器时遇到KeyError，已通过终端安装Flask和Flask-Mail。

报错代码 #

import os
import re

from flask import Flask, render_template,request,redirect
from flask_mail import Mail, Message
from cs50 import SQL

app = Flask(__name__)

app.config["MAIL_DEFAULT_SENDER"] = os.environ["MAIL_DEFAULT_SENDER"]
app.config["MAIL_PASSWORD"] = os.environ["MAIL_PASSWORD"]
app.config["MAIL_PORT"] = 587
# tcp port
app.config["MAIL_SERVER"] = "smtp.gmail.com"
app.config["MAIL_USE_TLS"] = True
# use encryption= true
app.config["MAIL_USERNAME"] = os.environ["MAIL_USERNAME"]

mail = Mail(app)
...

错误信息 #

Traceback (most recent call last):
  File "/opt/cs50/lib/flask", line 19, in <module>
    sys.exit(flask.cli.main())
  File "/usr/local/lib/python3.10/site-packages/flask/cli.py", line 1047, in main
    cli.main()
  File "/usr/local/lib/python3.10/site-packages/click/core.py", line 1055, in main
    rv = self.invoke(ctx)
  File "/usr/local/lib/python3.10/site-packages/click/core.py", line 1657, in invoke
    return _process_result(sub_ctx.command.invoke(sub_ctx))
  File "/usr/local/lib/python3.10/site-packages/click/core.py", line 1404, in invoke
    return ctx.invoke(self.callback, **ctx.params)
  File "/usr/local/lib/python3.10/site-packages/click/core.py", line 760, in invoke
    return __callback(*args, **kwargs)
  File "/usr/local/lib/python3.10/site-packages/click/decorators.py", line 84, in new_func
    return ctx.invoke(f, obj, *args, **kwargs)
  File "/usr/local/lib/python3.10/site-packages/click/core.py", line 760, in invoke
    return __callback(*args, **kwargs)
  File "/usr/local/lib/python3.10/site-packages/flask/cli.py", line 911, in run_command
    raise e from None
  File "/usr/local/lib/python3.10/site-packages/flask/cli.py", line 897, in run_command
    app = info.load_app()
  File "/usr/local/lib/python3.10/site-packages/flask/cli.py", line 312, in load_app
froshims5/ $     app = locate_app(import_name, None, raise_if_not_found=False)
  File "/usr/local/lib/python3.10/site-packages/flask/cli.py", line 218, in locate_app
    __import__(module_name)
  File "/workspaces/103199450/froshims5/app.py", line 10, in <module>
    app.config["MAIL_DEFAULT_SENDER"] = os.environ["MAIL_DEFAULT_SENDER"]
  File "/usr/local/lib/python3.10/os.py", line 679, in __getitem__
    raise KeyError(key) from None
KeyError: 'MAIL_DEFAULT_SENDER'

问题原因 #

代码中尝试通过os.environ["KEY"]读取环境变量，但MAIL_DEFAULT_SENDER（以及后续的MAIL_PASSWORD、MAIL_USERNAME）未在系统环境中设置，导致Python找不到对应键值，抛出KeyError。

解决方法 #

1. 直接在终端设置环境变量 #

根据你的操作系统执行对应命令（替换为你的实际邮箱信息）：

• Linux/macOS终端：

  export MAIL_DEFAULT_SENDER="your-email@gmail.com"
  export MAIL_USERNAME="your-email@gmail.com"
  export MAIL_PASSWORD="your-app-password"
  

• Windows CMD：

  set MAIL_DEFAULT_SENDER=your-email@gmail.com
  set MAIL_USERNAME=your-email@gmail.com
  set MAIL_PASSWORD=your-app-password
  

• Windows PowerShell：

  $env:MAIL_DEFAULT_SENDER="your-email@gmail.com"
  $env:MAIL_USERNAME="your-email@gmail.com"
  $env:MAIL_PASSWORD="your-app-password"
  

注意：如果使用Gmail且开启了两步验证，必须使用应用专用密码，不能用普通登录密码。

2. 使用.env文件管理环境变量（推荐） #

这种方式更便于项目维护，避免每次启动都手动设置：

• 安装依赖：

  pip install python-dotenv
  

• 在项目根目录创建.env文件，写入：

  MAIL_DEFAULT_SENDER=your-email@gmail.com
  MAIL_USERNAME=your-email@gmail.com
  MAIL_PASSWORD=your-app-password
  

• 在代码开头添加加载逻辑：

  from dotenv import load_dotenv
  load_dotenv()  # 加载.env中的环境变量
  

3. 临时硬编码（仅本地测试用，禁止生产环境） #

如果只是快速测试，可以直接把值写在代码里：

app.config["MAIL_DEFAULT_SENDER"] = "your-email@gmail.com"
app.config["MAIL_PASSWORD"] = "your-app-password"
app.config["MAIL_USERNAME"] = "your-email@gmail.com"

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