FastAPI搭建GET接口返回本地Word文档遇内部服务器错误求助

核心问题排查点 #

• 路径转义错误：你写的"C:\Users\Yaz\Desktop\"里的\U、\Y会被Python识别为转义字符，导致路径解析失败。必须改成原始字符串（加r前缀）或者用双反斜杠：

  # 两种正确写法
  word_document_path = r"C:\Users\Yaz\Desktop\"
  # 或者
  word_document_path = "C:\\Users\\Yaz\\Desktop\\"
  

• 文件名缺失后缀：Word文档（.docx）需要带后缀名，你当前拼接的路径是C:\Users\Yaz\Desktop\documentation，系统找不到无后缀的文件，要改成"documentation.docx"。
• 文件权限/存在性：检查目标文件是否真的存在，以及FastAPI运行进程有没有读取该文件的权限（比如Windows下是否被其他程序锁定，或者用户权限不足）。

调试技巧（新手必备） #

在代码里加异常捕获和文件校验，控制台会直接输出错误原因：

from fastapi import HTTPException
import os

@app.get("/file/uploadndownload")
def upload_n_downloadfile():
    try:
        word_document_path = r"C:\Users\Yaz\Desktop\"
        SAVE_FILE_PATH = os.path.join(word_document_path, "documentation.docx")
        
        # 先检查文件是否存在
        if not os.path.isfile(SAVE_FILE_PATH):
            raise HTTPException(status_code=404, detail="文件不存在")
            
        return FileResponse(
            path=SAVE_FILE_PATH,
            filename="documentation.docx",
            media_type="application/vnd.openxmlformats-officedocument.wordprocessingml.document"
        )
    except Exception as e:
        # 打印错误到控制台，直接看问题根源
        print(f"错误详情: {str(e)}")
        raise HTTPException(status_code=500, detail=str(e))

另外，启动FastAPI时用uvicorn main:app --reload，控制台会输出完整的错误堆栈，精准定位问题。

修复后的完整代码 #

from fastapi import FastAPI, HTTPException
from fastapi.responses import FileResponse
import os

app = FastAPI()

@app.get("/file/uploadndownload")
def upload_n_downloadfile():
    # 用原始字符串避免转义问题
    word_document_path = r"C:\Users\Yaz\Desktop\"
    file_name = "documentation.docx"
    SAVE_FILE_PATH = os.path.join(word_document_path, file_name)
    
    # 校验文件是否存在且是文件（不是文件夹）
    if not os.path.isfile(SAVE_FILE_PATH):
        raise HTTPException(status_code=404, detail=f"未找到文件: {file_name}")
    
    return FileResponse(
        path=SAVE_FILE_PATH,
        filename=file_name,
        media_type="application/vnd.openxmlformats-officedocument.wordprocessingml.document"
    )

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