정적 파일 서빙

웹 애플리케이션에서는 JSON이나 HTML 응답 외에도 CSS, JavaScript, 이미지, 웹 폰트 등의 다양한 정적 리소스를 제공해야 합니다. 이러한 파일들을 정적(static) 파일이라고 하며, FastAPI는 이를 효율적으로 처리할 수 있는 내장 기능을 제공합니다.

기본 설정

정적 파일 서빙을 위해서는 StaticFiles 클래스를 사용하여 애플리케이션에 마운트합니다:

from fastapi import FastAPI
from fastapi.staticfiles import StaticFiles

app = FastAPI()

app.mount(
    "/static",                             # URL 접두사 (prefix)
    StaticFiles(directory="staticfiles"),  # 실제 파일이 위치한 디렉토리
    name="static",                         # 템플릿에서 url_for 함수에 사용할 이름
)

위 설정으로 staticfiles 디렉토리의 파일들이 /static URL 경로로 접근 가능해집니다.

파일 접근 예시

프로젝트 구조가 다음과 같다면:

project/
├── entry.py
└── staticfiles/
    ├── css/
    │   └── style.css
    ├── js/
    │   └── app.js
    └── images/
        └── logo.png

각 파일은 다음 URL로 접근할 수 있습니다:

staticfiles/css/style.css → /static/css/style.css
staticfiles/js/app.js → /static/js/app.js
staticfiles/images/logo.png → /static/images/logo.png

HTML에서 정적 파일 사용

웹페이지에서 정적 파일을 참조할 때는 다음과 같이 사용합니다:

<!-- CSS 파일 -->
<link rel="stylesheet" href="/static/css/style.css">

<!-- JavaScript 파일 -->
<script src="/static/js/app.js"></script>

<!-- 이미지 파일 -->
<img src="/static/images/logo.png" alt="로고">

URL 동적 생성

하드코딩된 URL 대신 url_for 함수를 사용하면 더 유연한 관리가 가능합니다. 이는 배포 환경에서 CDN이나 다른 정적 파일 서버로 변경할 때 특히 유용합니다.

<!-- 권장하지 않는 방식 (하드코딩) -->
<link rel="stylesheet" href="/static/css/style.css">

<!-- 권장하는 방식 (동적 생성) -->
<link rel="stylesheet" href="{{ url_for('static', path='css/style.css') }}">
<script src="{{ url_for('static', path='js/app.js') }}"></script>
<img src="{{ url_for('static', path='images/logo.png') }}" alt="로고">

보안 고려사항

정적 파일 디렉토리는 공개적으로 접근 가능하므로, 민감한 정보가 포함된 파일은 해당 디렉토리에 두지 않도록 주의해야 합니다. 또한 파일 업로드 기능이 있다면 적절한 검증과 제한을 설정하는 것이 중요합니다.재시도Claude는 실수를 할 수 있습니다. 응답을 반드시 다시 확인해 주세요.