정적 파일

정적 파일 (Static Files)

웹 앱을 만들다 보면 이미지나 CSS, JavaScript처럼 서버가 그대로 내려주기만 하면 되는 파일이 있어요. 이런 걸 정적 파일(static files)이라고 해요. FastAPI는 StaticFiles를 이용해 특정 디렉토리에 든 정적 파일을 자동으로 서빙할 수 있게 해 줘요.

출처: 공식문서

팁

프론트엔드(SPA 등)를 호스팅해야 한다면 app.frontend()를 쓰는 게 더 나아요. 자세한 내용은 Frontend 문서에 있어요. app.frontend()는 내부적으로 StaticFiles를 사용하면서, 클라이언트 사이드 라우팅 처리 같은 프론트엔드에 유리한 추가 기능을 더해 줘요.

StaticFiles 사용하기

정적 파일을 서빙하려면 두 가지만 하면 돼요.

  1. StaticFiles를 가져온다.
  2. 특정 경로에 StaticFiles() 인스턴스를 **마운트(mount)**한다.
from fastapi import FastAPI
from fastapi.staticfiles import StaticFiles

app = FastAPI()

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

기술적 세부 사항

from starlette.staticfiles import StaticFiles처럼 Starlette에서 가져올 수도 있어요. fastapi.staticfiles는 개발자를 위해 같은 것을 그대로 다시 내놓은 별칭이에요. 실제 구현은 Starlette에서 온다고 보면 돼요.

"마운트(mount)"가 뭔가요?

마운트란, 하나의 완전히 "독립적인" 애플리케이션을 특정 경로에 붙여서, 그 경로 아래의 모든 하위 경로를 그 애플리케이션이 알아서 처리하게 하는 걸 말해요.

여기서 중요한 건 이게 APIRouter를 쓰는 것과는 다르다는 점이에요. 마운트된 애플리케이션은 완전히 독립적이라서, 메인 애플리케이션의 OpenAPI나 문서에는 마운트된 부분이 전혀 포함되지 않아요. 더 자세한 내용은 Advanced User Guide에서 다뤄요. 지금은 "마운트하면 그 경로 아래는 독립 앱이 맡는다"는 느낌만 잡아 두면 돼요.

인자 하나씩 뜯어보기

app.mount("/static", StaticFiles(directory="static"), name="static")
  • "/static" — 이 "하위 애플리케이션"이 마운트될 경로예요. "/static"으로 시작하는 모든 경로는 여기로 들어와요. 예를 들어 /static/image.png 같은 요청은 이 마운트된 앱이 처리하죠.
  • directory="static" — 정적 파일이 들어 있는 디렉토리 이름이에요.
  • name="static" — FastAPI가 내부적으로 사용할 수 있게 붙여 주는 이름이에요.

이렇게 하면 서버의 static/ 디렉토리 안에 image.png 같은 파일을 넣어 두고, 브라우저에서 /static/image.png로 접근하면 파일이 그대로 내려와요.

더 알아보기 (Learn more)