Flask: tách template và static riêng cho từng Blueprint — hết cảnh templates/ phình to trong 5 phút
Khi app Flask lớn dần, mọi template và file tĩnh dồn hết vào templates/ và static/ ở gốc sẽ nhanh chóng thành một mớ hỗn độn: hai module dễ đụng tên index.html hay style.css, và khi muốn mang một module sang project khác thì template của nó bị bỏ lại. Cách sửa gọn nhất: truyền template_folder và static_folder khi tạo Blueprint, để mỗi module tự mang theo template và file tĩnh của mình.
Vấn đề
Giả sử app có hai blueprint — admin và shop — và cả hai đều cần một trang index.html. Không có thư mục riêng, cả hai file phải nằm chung trong templates/, nhưng chỉ một file được mang tên đó. Cách chữa cháy thường thấy là đặt tên dài kiểu admin_index.html và shop_index.html: càng thêm module, tên file càng dài, càng khó biết file nào thuộc module nào. File tĩnh cũng vậy: static/style.css không cho biết đó là CSS của admin hay của shop, và khi chuyển module admin sang project khác, bạn phải đi lùng từng file của nó rải rác khắp các thư mục dùng chung.
# app.py — mọi template dồn vào templates/ ở gốc
admin = Blueprint("admin", __name__)
shop = Blueprint("shop", __name__)
@admin.route("/")
def admin_index():
return render_template("index.html") # của admin hay shop?
@shop.route("/")
def shop_index():
return render_template("index.html") # trùng tên — chỉ một file tồn tại
Cách làm
Truyền template_folder và static_folder khi tạo blueprint, rồi đặt template của nó trong thư mục con mang tên blueprint:
# blueprints/admin/__init__.py
from flask import Blueprint, render_template
admin = Blueprint(
"admin", __name__,
url_prefix="/admin",
template_folder="templates",
static_folder="static",
)
@admin.route("/")
def index():
return render_template("admin/index.html")
Cấu trúc thư mục lúc này:
blueprints/
admin/
__init__.py
templates/
admin/
index.html
static/
admin.css
Trong template, trỏ tới file tĩnh của blueprint qua endpoint admin.static:
<link rel="stylesheet" href="{{ url_for('admin.static', filename='admin.css') }}">
Vài điều cần nhớ
- Thư mục template của blueprint được thêm vào đường tìm kiếm với độ ưu tiên thấp hơn
templates/của app, nên app vẫn có thể override template của blueprint khi cần. - Đặt template trong thư mục con mang tên blueprint (
admin/index.html) để tránh bị override ngoài ý muốn: nếu hai blueprint cùng cóindex.htmlở gốc thư mục template của mình, blueprint đăng ký trước sẽ thắng. static_folderchỉ truy cập được khi blueprint cóurl_prefix— mặc định file nằm ở/admin/static/admin.css. Không có prefix, route/staticcủa app sẽ chiếm ưu thế và file tĩnh của blueprint không truy cập được.url_for("admin.static", filename="admin.css")sinh URL đúng ngay cả khi bạn đổiurl_prefixsau này, nên đừng hardcode/admin/static/...trong template.- Khi Flask load nhầm template, bật
app.config["EXPLAIN_TEMPLATE_LOADING"] = Trueđể Flask in từng bước tìm kiếm.
Áp dụng vào project của bạn
Kết hợp với Application Factory, mỗi blueprint trở thành một thư mục tự chứa route, template và file tĩnh — copy cả thư mục sang project khác là chạy ngay. Chỉ giữ trong templates/ gốc những gì cả app dùng chung, như base.html, macro và trang lỗi; chỉ tách ra những gì thuộc về đúng một module. Module nhỏ chỉ có một hai template thì không cần thư mục riêng — hãy tách khi tên file bắt đầu phải gắn thêm tên module chỉ để tránh đụng tên.
Hỏi đáp nhanh
Không truyền template_folder, blueprint tìm template ở đâu?
Chỉ trong templates/ của app. Truyền template_folder sẽ thêm thư mục riêng của blueprint vào đường tìm kiếm, và thư mục của app vẫn được ưu tiên.
Hai blueprint cùng có index.html — Flask chọn file nào?
Template của app thắng trước; trong các blueprint, blueprint đăng ký trước thắng. Cách an toàn nhất: đặt template trong thư mục con mang tên blueprint, ví dụ admin/index.html.
Vì sao url_for('admin.static', ...) trả 404 dù file vẫn có?
Thường vì blueprint không có url_prefix, nên route /static của app chiếm ưu thế. Thêm url_prefix="/admin" (hoặc static_url_path) rồi kiểm tra lại /admin/static/<filename>.
Đọc bản đầy đủ (tiếng Anh) tại: https://linhfish.dev/en/2026/11/22/flask-separate-templates-and-static-files-per-blueprint-stop-your-templates-folder-from-ballooning-in-5-minutes/
All rights reserved