Flask子域名配置问题：本地、Ngrok及Render部署失效排查

一、本地开发环境修复 #

1. 修改代码配置根域名 #

Flask默认不识别子域名，必须通过SERVER_NAME指定根域名才能解析路由中的subdomain参数，同时避免函数名与参数名冲突：

from flask import Flask

app = Flask(__name__)
# 配置本地根域名，需包含端口号
app.config['SERVER_NAME'] = 'localhost:5000'

@app.route('/')
def index():
    return 'This is the main domain.'

@app.route('/', subdomain='<subdomain>')
def subdomain_handler(subdomain):
    return f'This is the subdomain: {subdomain}'

if __name__ == '__main__':
    app.run(debug=True)

2. 验证与重启 #

确认hosts文件已添加127.0.0.1 sub.localhost，保存后重启Flask服务，访问sub.localhost:5000即可正常加载子域名内容。

二、Ngrok隧道场景配置 #

1. 启动Ngrok时指定自定义子域名（免费版可用临时子域名，Pro版支持固定子域名）：

ngrok http --subdomain=sub 5000

此时会生成类似sub.xxx.ngrok.io的访问地址。

2. 修改Flask的SERVER_NAME为Ngrok分配的根域名（去掉子域名前缀）：

app.config['SERVER_NAME'] = 'xxx.ngrok.io'  # 替换为实际的Ngrok根域名

3. 重启Flask服务，访问sub.xxx.ngrok.io即可触发子域名路由。

三、Render部署场景配置 #

1. 添加子域名解析
   进入Render应用的Settings→Custom Domains，添加子域名（如sub.your-app.onrender.com），按照提示将子域名的CNAME记录指向Render提供的目标地址，等待DNS解析生效。

2. 配置Flask环境变量
   通过环境变量设置SERVER_NAME，避免硬编码：

import os
from flask import Flask

app = Flask(__name__)
# 从环境变量读取根域名，本地开发默认用localhost:5000
app.config['SERVER_NAME'] = os.getenv('SERVER_NAME', 'localhost:5000')

@app.route('/')
def index():
    return 'This is the main domain.'

@app.route('/', subdomain='<subdomain>')
def subdomain_handler(subdomain):
    return f'This is the subdomain: {subdomain}'

3. 设置Render环境变量
   在Render应用的Environment配置中添加SERVER_NAME变量，值为你的主域名（如your-app.onrender.com），重新部署应用后，访问sub.your-app.onrender.com即可正常工作。

关键注意事项 #

• SERVER_NAME必须是不带子域名的根域名，Flask会自动解析请求中的子域名部分匹配路由。
• 部署场景需确保DNS解析完全生效后再测试子域名访问。

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