SQLAdmin模板覆盖问题解析：解决list.html找不到的异常

2025-07-04 13:28:21作者：柯茵沙

SQLAlchemy Admin for FastAPI and Starlette

项目地址：https://gitcode.com/gh_mirrors/sq/sqladmin

在使用SQLAdmin进行后台管理开发时，模板覆盖是一个常见的定制化需求。近期有开发者反馈在覆盖list模板时遇到了jinja2.exceptions.TemplateNotFound: list.html异常，这实际上是由于SQLAdmin项目内部结构调整导致的兼容性问题。

问题背景

SQLAdmin作为一个基于SQLAlchemy的管理界面框架，允许开发者通过模板继承的方式定制界面。在之前的版本中，开发者可以直接通过{% extends "list.html" %}来继承基础列表模板。然而，随着项目的发展，为了提供更好的模板管理体验，SQLAdmin团队对模板目录结构进行了优化调整。

问题原因

问题的根源在于SQLAdmin将模板文件移动到了专门的sqladmin子目录中。这一变更使得直接引用list.html的方式不再有效，因为模板引擎现在需要在sqladmin/路径下查找模板文件。

解决方案

要解决这个问题，开发者需要更新模板继承语句，明确指定模板的完整路径：

{% extends "sqladmin/list.html" %}
{% block content %}
    {{ super() }}
    <head>
        <style>
            td {max-width: 250px; text-overflow: ellipsis; overflow: hidden;}
        </style>
    </head>
{% endblock %}

最佳实践

版本兼容性检查：在进行模板覆盖前，建议先查看当前使用的SQLAdmin版本，了解其模板结构
模板路径规范：对于任何第三方库的模板覆盖，建议都使用完整路径引用，避免因内部结构调整导致的问题
样式定制技巧：如示例所示，可以通过添加CSS样式来调整表格单元格的显示效果，实现更好的用户体验
变更日志关注：定期查看项目更新日志，特别是涉及模板结构调整的变更，可以提前预防类似问题

总结

SQLAdmin的这次模板结构调整虽然带来了短暂的兼容性问题，但从长远来看，这种命名空间的规范化有利于项目的维护和发展。开发者只需做简单的路径调整即可适应这一变化，继续享受SQLAdmin提供的强大管理界面功能。

SQLAlchemy Admin for FastAPI and Starlette

项目地址：https://gitcode.com/gh_mirrors/sq/sqladmin

登录后查看全文

项目优选

收起

deepin linux kernel

OpenHarmony documentation | OpenHarmony开发者文档

Ascend Extension for PyTorch

本项目是CANN提供的数学类基础计算算子库，实现网络在NPU上加速计算。

openEuler内核是openEuler操作系统的核心，既是系统性能与稳定性的基石，也是连接处理器、设备与服务的桥梁。

openJiuwen agent-studio提供零码、低码可视化开发和工作流编排，模型、知识库、插件等各资源管理能力

openGauss-server

openGauss kernel ~ openGauss is an open source relational database management system

flutter_flutter

🎉 (RuoYi)官方仓库基于SpringBoot，Spring Security，JWT，Vue3 & Vite、Element Plus 的前后端分离权限管理系统

华为昇腾面向大规模分布式训练的多模态大模型套件，支撑多模态生成、多模态理解。