Flask与Jinja模板content块堆叠问题：重定向引发渲染异常

问题根源 #

你使用htmx的hx-post异步提交表单，路由处理POST请求后返回redirect(request.url)，htmx会自动跟随重定向并获取完整HTML页面，默认将响应内容替换触发请求的表单容器。由于完整页面包含了基础模板的所有结构（导航、content块、脚本等），最终导致content块被重复插入，出现堆叠异常。

解决方案 #

方案1：改用普通表单提交（最简单） #

移除表单上的hx-post属性，使用标准HTML表单提交方式：

<form method="post" enctype="multipart/form-data">
    <div class="mb-3">
        <label for="formFile" class="form-label">Default file input example</label>
        <input class="form-control" type="file" id="formFile" name="file">
        <button>Upload</button>
    </div>
</form>

此方式下浏览器会正常处理重定向，刷新整个页面，避免内容堆叠。

方案2：针对htmx请求返回HX-Redirect头 #

在路由中判断是否为htmx请求，返回HX-Redirect头让htmx执行页面跳转，而非返回重定向响应：

@app.route("/upload", methods=["POST", "GET"])
def upload():
    logging.create_logger(app=app).warn("upload route")
    if request.method == "POST":
        logging.create_logger(app=app).warn("Post method reach")
        # 检查POST请求是否包含文件部分
        if "file" not in request.files:
            logging.create_logger(app=app).warn("No file")
            flash("No file part", "error")
            # 判断是否是htmx请求
            if request.headers.get("HX-Request"):
                return "", 200, {"HX-Redirect": request.url}
            return redirect(request.url)
        file = request.files["file"]
        # 用户未选择文件时，浏览器会提交空文件名的文件
        if file.filename == "":
            flash("No selected file", "error")
            logging.create_logger(app=app).warn("No selected file")
            if request.headers.get("HX-Request"):
                return "", 200, {"HX-Redirect": request.url}
            return redirect(request.url)
        logging.create_logger(app=app).warn("{}".format(file.filename))
        if file and file.filename and allowed_file(file.filename):
            filename = secure_filename(file.filename)
            flash("File uploaded: {}".format(filename), "success")
            file.save(os.path.join(app.config["UPLOAD_FOLDER"], filename))
            logging.create_logger(app=app).warn("Upload successful")
            if request.headers.get("HX-Request"):
                return "", 200, {"HX-Redirect": request.url}
            return redirect(request.url)
        else:
            flash("File extension not allowed", "error")
            if request.headers.get("HX-Request"):
                return "", 200, {"HX-Redirect": request.url}
            return redirect(request.url)
    return render_template("fragments/upload.html.j2")

此方式下htmx会收到跳转指令，刷新整个页面，保持异步提交的同时避免内容插入错误。

方案3：htmx请求时返回模板片段（保持异步无刷新） #

如果希望保留异步提交的无刷新体验，可以让htmx请求仅返回表单片段：

1. 创建独立的表单片段模板upload_form.html.j2：

<div class="container">
    <div class="row">
        <div class="col-lg-12">
            <form hx-encoding="multipart/form-data" hx-post="/upload">
                <div class="mb-3">
                    <label for="formFile" class="form-label">Default file input example</label>
                    <input class="form-control" type="file" id="formFile" name="file">
                    <button>Upload</button>
                </div>
            </form>
        </div>
    </div>
</div>

2. 修改路由，根据请求类型返回完整页面或片段：

@app.route("/upload", methods=["POST", "GET"])
def upload():
    logging.create_logger(app=app).warn("upload route")
    is_htmx = request.headers.get("HX-Request")
    if request.method == "POST":
        logging.create_logger(app=app).warn("Post method reach")
        # 检查POST请求是否包含文件部分
        if "file" not in request.files:
            logging.create_logger(app=app).warn("No file")
            flash("No file part", "error")
            if is_htmx:
                return render_template("upload_form.html.j2")
            return redirect(request.url)
        file = request.files["file"]
        # 用户未选择文件时，浏览器会提交空文件名的文件
        if file.filename == "":
            flash("No selected file", "error")
            logging.create_logger(app=app).warn("No selected file")
            if is_htmx:
                return render_template("upload_form.html.j2")
            return redirect(request.url)
        logging.create_logger(app=app).warn("{}".format(file.filename))
        if file and file.filename and allowed_file(file.filename):
            filename = secure_filename(file.filename)
            flash("File uploaded: {}".format(filename), "success")
            file.save(os.path.join(app.config["UPLOAD_FOLDER"], filename))
            logging.create_logger(app=app).warn("Upload successful")
            if is_htmx:
                return render_template("upload_form.html.j2")
            return redirect(request.url)
        else:
            flash("File extension not allowed", "error")
            if is_htmx:
                return render_template("upload_form.html.j2")
            return redirect(request.url)
    # GET请求时，根据是否是htmx请求返回对应内容
    if is_htmx:
        return render_template("upload_form.html.j2")
    return render_template("fragments/upload.html.j2")

若需要在异步提交后显示flash消息，可以调整基础模板中的消息渲染区域，添加hx-swap-oob="true"属性，让htmx单独更新消息区域。

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