路径基准判断错误是最常见的起因

Flask 蓝图的 template_folder 参数默认使用相对路径，但该路径是相对于蓝图对象定义所在文件的目录，而非项目根目录或 Flask 应用对象所在的目录。如果你在子目录下定义蓝图，例如 myapp/admin/views.py，并设置 template_folder='templates'，实际访问的是 myapp/admin/templates/，而不是项目根目录下的 templates。常见的无效情形是误以为路径相对于 app 根目录，导致 Flask 找不到模板文件。如果你遇到模板 404，第一步就是确认蓝图文件的实际位置，然后手动计算 template_folder 对应到文件系统的绝对路径。可以在蓝图定义处临时加一行打印：print(os.path.abspath('templates'))，观察输出结果是否符合预期。如果路径指向了不存在的文件夹，就说明基准判断错了。

Flask 蓝图的 template_folder 参数默认使用相对路径，但该路径是相对于蓝图对象定义所在文件的目录，而非项目根目录或 Flask 应用对象所在的目录。如果你在子目录下定义蓝图，例如 `myapp/admin/views.py`，并设置 `template_folder='templates'`，实际访问的是 `myapp/admin/templates/`，而不是项目根目录下的 `templates`。常见的无效情形是误以为路径相对于 app 根目录，导致 Flask 找不到模板文件。

许多开发者只将蓝图对象注册到 Flask 应用，却忘记在创建蓝图时指定 template_folder。例如 `admin_bp = Blueprint('admin', __name__)` 默认不包含模板文件夹，后续注册不会自动分配。正确的做法是在构造函数中显式传入：`admin_bp = Blueprint('admin', __name__, template_folder='templates')`。如果遗漏，即使模板物理路径存在，Flask 也不会搜索该蓝图下的模板。

创建蓝图时忘记指定 template_folder

许多开发者只将蓝图对象注册到 Flask 应用，却忘记在创建蓝图时指定 template_folder。例如 admin_bp = Blueprint('admin', __name__) 默认不包含模板文件夹，后续注册不会自动分配。正确的做法是在构造函数中显式传入：admin_bp = Blueprint('admin', __name__, template_folder='templates')。如果遗漏，即使模板物理路径存在，Flask 也不会搜索该蓝图下的模板。检查时，可以查看蓝图对象的属性：print(admin_bp.template_folder)，如果返回 None 就表示未设置。修复后需要重启应用，因为 Blueprint 实例化时的参数只在创建时生效。

模板搜索优先级导致同名文件被覆盖

Flask 渲染模板时，先搜索应用级别的 app.template_folder 目录，再搜索当前活动蓝图的 template_folder。这意味着如果两个位置存在同名模板，应用级别的模板会覆盖蓝图的模板，容易造成“路径设置无效”的假象。建议在蓝图中使用带前缀的模板名，例如 admin/index.html，并确保应用级目录下无同名文件，或直接通过 app.template_folder 回归测试。如果你发现蓝图的模板始终不生效，可以先在应用级模板文件夹下搜索同名文件，如果有，删除或改名后重启。另外，可以调用 app.jinja_env.list_templates() 列出所有可用的模板，确认蓝图中的文件是否在列表里，以及是否被其他同名文件覆盖。

用绝对路径消除不确定性

如果相对路径始终不生效，可改用基于当前文件路径构建的绝对路径。例如在蓝图文件中写入 import os; template_folder=os.path.join(os.path.dirname(__file__), 'templates')。这样做能消除相对路径的不确定性，但注意保持路径跨平台兼容性，避免硬编码。不过绝对路径会使蓝图的可移植性降低，移动蓝图文件后需要同步修改路径。这个方案适合以下场景：蓝图文件位置固定，且不打算在不同环境间复用。使用后，可以再次打印 admin_bp.template_folder 确认绝对路径指向真实的文件夹。

检查工作目录与环境差异

开发环境与生产环境的工作目录可能不同，导致相对路径解析结果异常。例如，通过 flask run 启动时工作目录是项目根目录，但使用 Gunicorn 或 uWSGI 启动时可能发生变化。如果蓝图的 template_folder 依赖于 __file__ 的相对路径，务必确保 __file__ 指向正确的模块文件。建议在蓝图定义处打印 os.path.abspath(template_folder) 验证实际路径是否符合预期。如果发现路径不对，可以考虑在蓝图文件中使用 os.path.dirname(os.path.abspath(__file__)) 来获取蓝图文件所在目录，再拼接模板文件夹。另外，部署时可以使用环境变量传入模板根目录，避免硬编码。

验证模板加载的实用检查

除了上面提到的打印方法，还可以利用 Flask 的调试模式查看错误栈。当模板未找到时，Flask 会抛出 TemplateNotFound 异常，异常信息中会包含搜索过的路径列表。在开发环境开启 app.debug = True，然后故意访问一个不存在的模板，浏览器的错误页会显示 Jinja 加载器搜索了哪些文件夹。这个列表可以直接告诉你蓝图模板文件夹是否被正确添加。如果列表中缺少蓝图路径，说明 registration 或 template_folder 配置有问题。如果路径存在但文件不在里面，那就是文件名或子目录层级写错了。