Starlette版本过高引发Jinja2报错TypeError unhashable type dict

一、先了解问题现象：

在完成HTML页面与路由配置后，原本期望能通过浏览器正常访问，却遭遇了“Internal Server Error”，页面显示为空白，没有任何错误提示信息。

二、快速定位错误原因

要获取更详细的错误信息，最简便的方式是在FastAPI实例化时设置debug=True参数。

app = FastAPI(title="智能语音AI袋里", description="提供预约管理、智能咨询、用户行为分析等功能的API服务", version="1.0.0", docs_url="/docs", redoc_url="/redoc", debug=True)

启用debug模式后，浏览器终于显示了具体的错误信息，如下图所示：

经过一番排查，发现问题根源在于Starlette的版本——当时使用的是1.3.1，该版本中Jinja2Templates的TemplateResponse返回值写法发生了变化。具体问题出现在Web路由的定义中：

@router.get("/test_knowledge_management", response_class=HTMLResponse, summary="知识库测试界面")
async def knowledge_test_page1(request: Request):
    """知识库测试界面"""
    return templates.TemplateResponse("test_knowledge_management.html", {"request": request})

在旧版本中，这种写法是可以正常运行的：直接使用templates.TemplateResponse("test_knowledge_management.html", {"request": request})。但在新版本中，TemplateResponse的第一个参数必须为request，只需调整参数顺序即可正常访问：

@router.get("/test_knowledge_management", response_class=HTMLResponse, summary="知识库测试界面")
async def knowledge_test_page1(request: Request):
    """知识库测试界面"""
    return templates.TemplateResponse(request, "test_knowledge_management.html", {"request": request})

三、使用AI工具辅助排查的体会

整个排查过程主要依靠AI助手分析原因，实事求是地说，AI工具确实高效，节省了大量时间和精力。但在实际使用中也总结出了一些经验和方法：

1、AI分析的准确性高度依赖于问题描述的清晰度和数据的完整性——如何准确地描述问题，直接决定了能否快速定位到根本原因。因此，编写优质的prompt（提示词）非常关键，需要认真推敲。

2、AI分析问题也存在明显的局限性：它只能根据你提供的片段内容进行推理，对项目的整体架构和上下文缺乏了解，无法结合实际情况做出判断，有时给出的结论并不可靠。