Flask Session API
Session 用于在同一用户的不同请求之间保存数据。Flask 默认使用签名 Cookie 实现，数据存储在客户端但无法被篡改。
通过 from flask import session 导入，像字典一样使用。
session 代理对象
session 是一个代理，指向当前请求的 SessionMixin 实例。只在请求上下文中可用。
| 属性/方法 | 说明 |
|---|---|
| session[key] = value | 设置 session 值 |
| session.get(key, default) | 安全获取 session 值，键不存在时返回 default |
| session.pop(key, default) | 移除并返回指定键的值 |
| session.clear() | 清空所有 session 数据 |
| "key" in session | 检查键是否存在 |
| session.permanent | 设为 True 时，Session 在浏览器关闭后仍保持（使用 PERMANENT_SESSION_LIFETIME） |
| session.modified | 当修改 session 中的可变值时（如列表 append），需手动设为 True |
| session.accessed | session 被访问时为 True，Flask 会自动添加 Vary: Cookie 头 |
| session.new | session 是否为新创建（部分实现不支持精确判断） |
当修改 session 中嵌套的可变对象（如列表、字典）时，Flask 无法自动检测到修改。
必须手动设置 session.modified = True，否则修改不会保存到 Cookie 中。
配置项
| 配置键 | 默认值 | 说明 |
|---|---|---|
| SECRET_KEY | None | 签名 Session 的密钥，必须设置才能使用 Session |
| SESSION_COOKIE_NAME | "session" | Session Cookie 的名称 |
| SESSION_COOKIE_DOMAIN | None | Cookie 的 Domain 属性 |
| SESSION_COOKIE_PATH | None | Cookie 的 Path 属性 |
| SESSION_COOKIE_HTTPONLY | True | 禁止 JavaScript 访问 Session Cookie |
| SESSION_COOKIE_SECURE | False | 为 True 时仅通过 HTTPS 发送 Cookie |
| SESSION_COOKIE_SAMESITE | None | "Strict"、"Lax" 或 None |
| PERMANENT_SESSION_LIFETIME | timedelta(days=31) | 永久 Session 的有效期 |
| SESSION_REFRESH_EACH_REQUEST | True | 每次请求都刷新 Session Cookie 的有效期 |
代码示例
实例
from flask import Flask, session, redirect, url_for
app = Flask(__name__)
app.secret_key = "your-secret-key"
@app.route("/")
def index():
if "username" in session:
return f'Logged in as {session["username"]}'
return 'You are not logged in'
@app.route("/login", methods=["GET", "POST"])
def login():
if request.method == "POST":
session["username"] = request.form["username"]
# 设置永久 session（浏览器关闭后保持 31 天）
session.permanent = True
return redirect(url_for("index"))
return '<form method="post"><input name="username"></form>'
@app.route("/appends")
def append_to_list():
# 注意：修改嵌套列表需要手动标记 modified
if "items" not in session:
session["items"] = []
session["items"].append("new_item")
session.modified = True # 必须手动标记！
return f'Items: {session["items"]}'
@app.route("/logout")
def logout():
session.clear()
return redirect(url_for("index"))
app = Flask(__name__)
app.secret_key = "your-secret-key"
@app.route("/")
def index():
if "username" in session:
return f'Logged in as {session["username"]}'
return 'You are not logged in'
@app.route("/login", methods=["GET", "POST"])
def login():
if request.method == "POST":
session["username"] = request.form["username"]
# 设置永久 session（浏览器关闭后保持 31 天）
session.permanent = True
return redirect(url_for("index"))
return '<form method="post"><input name="username"></form>'
@app.route("/appends")
def append_to_list():
# 注意：修改嵌套列表需要手动标记 modified
if "items" not in session:
session["items"] = []
session["items"].append("new_item")
session.modified = True # 必须手动标记！
return f'Items: {session["items"]}'
@app.route("/logout")
def logout():
session.clear()
return redirect(url_for("index"))