flask 3.1.0 起默认禁用子域名匹配，即使设置了 server_name，也必须显式启用 subdomain_matching=true，否则带 subdomain 的路由全部返回 404。
flask 3.1.0 起默认禁用子域名匹配，即使设置了 server_name，也必须显式启用 subdomain_matching=true，否则带 subdomain 的路由全部返回 404。
在 Flask 3.1.0 中，子域名支持机制发生了关键变更：subdomain_matching 不再默认启用，即使你已正确配置 SERVER_NAME 和 SESSION_COOKIE_DOMAIN，也不会自动激活子域名路由解析。这意味着所有形如 user.example.com 的请求无法匹配到 @app.route('/', subdomain='
正确配置步骤
-
初始化应用时显式启用子域名匹配
from flask import Flask app = Flask(__name__, subdomain_matching=True)
-
设置 SERVER_NAME（必需）
SERVER_NAME 必须明确指定为不含协议和路径的主域名（如 "example.com"），Flask 依赖它从 Host 头中提取子域名：app.config['SERVER_NAME'] = 'example.com' # 注意：不带 http://，不带 www
-
配置会话 Cookie 域（可选但推荐）
确保登录态跨子域名共享：app.config['SESSION_COOKIE_DOMAIN'] = '.example.com' # 开头带点，表示通配所有子域
-
定义子域名路由（保持原有写法）
@app.route('/', subdomain='<username>') def user_dashboard(username): return f"Welcome, {username}!"</username>
✅ 此时访问 alice.example.com 将正确匹配并执行该视图；
❌ 若遗漏 subdomain_matching=True，即使 SERVER_NAME 设置正确，Flask 3.1.0+ 仍会忽略 subdomain 参数，导致 404。
注意事项与常见陷阱
- SERVER_NAME 不能设为 www.example.com 或 http://example.com，否则子域名提取失败；
- 启用 subdomain_matching=True 后，所有路由默认绑定到主域名（即 example.com），除非显式声明 subdomain；
- 开发时若使用 localhost，需通过 hosts 文件模拟子域名（如 127.0.0.1 alice.localhost），并设 SERVER_NAME='localhost:5000'；
- 生产环境建议配合反向代理（如 Nginx）正确传递 Host 头，避免代理层覆盖原始域名。
升级至 Flask 3.1.0 后，请务必检查应用初始化逻辑——subdomain_matching=True 是子域名功能的开关，而非可选优化项。官方文档虽提及 SERVER_NAME 在启用子域名匹配时“必须设置”，但未强调该选项本身已从隐式默认变为显式必需，这是本次升级中最易被忽略的关键变更。
