FastAPI中static路由挂载失败：NoMatchFound错误求助

问题描述 #

原本基于FastAPI开发纯REST API服务，因外部服务需重定向至页面，添加Jinja2Templates后成功调用HTML模板。随后将Bootstrap模板放入static文件夹并尝试挂载，但在分离的路由文件中无法完成挂载，出现starlette.routing.NoMatchFound: No route exists for name "static" and params "filename"错误。

项目目录结构 #

another projects
target project
|- src
   |- app
      |- main.py
      |- controllers
         |- page_controller.py
      |- endpoints
         |- from_external_redirec.py
      |- routes
         |- api.py
      |- schemas
      |- static    <- 新增目录
      |- templates <- 新增目录
         |- success.html
         |- fault.html

注：该目录用于Docker容器，目标项目是其中一个容器

相关代码及问题分析与修复 #

1. main.py（核心路径错误） #

原代码存在静态资源路径拼接错误，导致StaticFiles无法找到正确目录：

from fastapi import FastAPI
import os
from fastapi.staticfiles import StaticFiles
from .app.routes.api import router as api_router

app = FastAPI(
    title="xxxxxxxx",
    description="xxxxx",
    version="0.0.1",
)

absolute_path = os.path.dirname(__file__)
relative_path = "app/static"
static_path = os.path.join(absolute_path, relative_path)

app.include_router(api_router)
app.mount("/static", StaticFiles(directory=static_path), name="static")

问题点：os.path.dirname(__file__)获取的是src/app目录（main.py所在路径），拼接app/static后得到src/app/app/static，与实际静态资源目录src/app/static不匹配，导致静态资源挂载失败。

修复后代码：

from fastapi import FastAPI
from pathlib import Path
from fastapi.staticfiles import StaticFiles
from .routes.api import router as api_router  # 修正冗余的app/导入路径

app = FastAPI(
    title="xxxxxxxx",
    description="xxxxx",
    version="0.0.1",
)

# 用Pathlib更可靠地定位静态资源目录
BASE_DIR = Path(__file__).parent
static_path = BASE_DIR / "static"

app.include_router(api_router)
app.mount("/static", StaticFiles(directory=static_path), name="static")

2. page_controller.py（方法名不匹配与路径优化） #

原代码方法名与路由文件调用的名称不一致，同时相对路径易产生歧义：

from fastapi.templating import Jinja2Templates
from fastapi.requests import Request
import os

class pagectl:
    def __init__(self):
        absolute_path = os.path.dirname(__file__)
        relative_path = "../templates"
        template_path = os.path.join(absolute_path, relative_path)
        self.template = Jinja2Templates(directory=template_path)
    
    def show_success_page(self, request: Request):
        return self.__get_template(request, "success.html")
        
    def show_fault_page(self, request: Request):
        return self.__get_template(request, "fault.html")

    def __get_template(self, request: Request, file: str):
        return self.template.TemplateResponse(
            file,
            {
                "request": request,
            }
        )

修复后代码：

from fastapi.templating import Jinja2Templates
from fastapi.requests import Request
from pathlib import Path

class pagectl:
    def __init__(self):
        # 用Pathlib避免相对路径歧义
        BASE_DIR = Path(__file__).parent.parent  # 从controllers目录定位到app根目录
        template_path = BASE_DIR / "templates"
        self.template = Jinja2Templates(directory=str(template_path))
    
    # 新增与路由调用匹配的方法名
    def get_successful_template(self, request: Request):
        return self.__get_template(request, "success.html")
        
    def get_cancel_template(self, request: Request):
        return self.__get_template(request, "fault.html")

    def __get_template(self, request: Request, file: str):
        return self.template.TemplateResponse(
            file,
            {
                "request": request,
            }
        )

3. from_external_redirec.py（语法错误与方法调用修正） #

原代码存在缩进错误、方法名拼写错误及参数缺失：

from fastapi import status as st, APIRouter, HTTPException, Request
from fastapi.responses import RedirectResponse, HTMLResponse
from fastapi.requests import Request
from requests import request
import os
from ..controllers.page_controller import pagectl

router = APIRouter(
    prefix="/external",
    tags=["External"],
)

@router.get("/result/success/", response_class=HTMLResponse)
async def show_success_page(request: Request):
    page = pagectl()
        return page.get_successful_template(request)
    return page.get_error_template(request)
    
@router.get("/result/cancel/{payment_id}", response_class=HTMLResponse)
async def show_falt_page(request: Request):
    page = pagectl()
    return page.get_cancel_template(request) 

修复后代码：

from fastapi import APIRouter, Request
from fastapi.responses import HTMLResponse
from ..controllers.page_controller import pagectl

router = APIRouter(
    prefix="/external",
    tags=["External"],
)

@router.get("/result/success/", response_class=HTMLResponse)
async def show_success_page(request: Request):
    page = pagectl()
    return page.get_successful_template(request)
    
@router.get("/result/cancel/{payment_id}", response_class=HTMLResponse)
async def show_fault_page(request: Request, payment_id: str):  # 修正方法名拼写，添加参数接收
    page = pagectl()
    return page.get_cancel_template(request) 

4. 模板文件（静态资源引用规范） #

在success.html/fault.html中引用静态资源时，必须使用url_for方法匹配挂载的static路由：

<!-- 示例：引用Bootstrap CSS -->
<link href="{{ url_for('static', filename='css/bootstrap.min.css') }}" rel="stylesheet">

<!-- 示例：引用Bootstrap JS -->
<script src="{{ url_for('static', filename='js/bootstrap.bundle.min.js') }}"></script>

注意：filename需对应static目录下的实际文件路径，如static/css/bootstrap.min.css则填写css/bootstrap.min.css。

验证步骤 #

1. 进入Docker容器执行ls /code/src/app/static，确认静态资源文件存在
2. 启动服务后访问http://localhost/static/css/bootstrap.min.css（对应资源路径），确认能正常返回资源
3. 检查Nginx配置是否正确转发/static路径的请求到FastAPI服务

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