靜態檔案 - StaticFiles

您可以使用 StaticFiles 類別來提供靜態檔案，例如 JavaScript、CSS、圖片等。

在FastAPI 靜態檔案文件中閱讀更多相關資訊。

您可以直接從 fastapi.staticfiles 導入它。

from fastapi.staticfiles import StaticFiles

fastapi.staticfiles.StaticFiles

StaticFiles(
    *,
    directory=None,
    packages=None,
    html=False,
    check_dir=True,
    follow_symlink=False
)

參數	說明
directory（目錄）	類型： PathLike | None 預設值： None
packages（套件）	類型： list[str | tuple[str, str]] | None 預設值： None
html	類型： bool 預設值： False
check_dir（檢查目錄）	類型： bool 預設值： True
follow_symlink（跟隨符號連結）	類型： bool 預設值： False

原始程式碼位於 starlette/staticfiles.py

def __init__(
    self,
    *,
    directory: PathLike | None = None,
    packages: list[str | tuple[str, str]] | None = None,
    html: bool = False,
    check_dir: bool = True,
    follow_symlink: bool = False,
) -> None:
    self.directory = directory
    self.packages = packages
    self.all_directories = self.get_directories(directory, packages)
    self.html = html
    self.config_checked = False
    self.follow_symlink = follow_symlink
    if check_dir and directory is not None and not os.path.isdir(directory):
        raise RuntimeError(f"Directory '{directory}' does not exist")

directory（目錄） 實例屬性

directory = directory

packages（套件） 實例屬性

packages = packages

all_directories（所有目錄） 實例屬性

all_directories = get_directories(directory, packages)

html 實例屬性

html = html

config_checked（已檢查設定） 實例屬性

config_checked = False

follow_symlink（跟隨符號連結） 實例屬性

follow_symlink = follow_symlink

get_directories（取得目錄）

get_directories(directory=None, packages=None)

給定 directory 和 packages 參數，返回應用於提供靜態檔案的所有目錄列表。

參數	說明
directory（目錄）	類型： PathLike | None 預設值： None
packages（套件）	類型： list[str | tuple[str, str]] | None 預設值： None

原始程式碼位於 starlette/staticfiles.py

def get_directories(
    self,
    directory: PathLike | None = None,
    packages: list[str | tuple[str, str]] | None = None,
) -> list[PathLike]:
    """
    Given `directory` and `packages` arguments, return a list of all the
    directories that should be used for serving static files from.
    """
    directories = []
    if directory is not None:
        directories.append(directory)

    for package in packages or []:
        if isinstance(package, tuple):
            package, statics_dir = package
        else:
            statics_dir = "statics"
        spec = importlib.util.find_spec(package)
        assert spec is not None, f"Package {package!r} could not be found."
        assert spec.origin is not None, f"Package {package!r} could not be found."
        package_directory = os.path.normpath(os.path.join(spec.origin, "..", statics_dir))
        assert os.path.isdir(
            package_directory
        ), f"Directory '{statics_dir!r}' in package {package!r} could not be found."
        directories.append(package_directory)

    return directories

get_path（取得路徑）

get_path(scope)

給定 ASGI 範圍，返回要提供的 `path` 字串，使用作業系統特定的路徑分隔符號，並移除任何 '..'、'.' 元件。

參數	說明
scope（範圍）	類型： Scope（範圍）

原始程式碼位於 starlette/staticfiles.py

def get_path(self, scope: Scope) -> str:
    """
    Given the ASGI scope, return the `path` string to serve up,
    with OS specific path separators, and any '..', '.' components removed.
    """
    route_path = get_route_path(scope)
    return os.path.normpath(os.path.join(*route_path.split("/")))

get_response（取得回應） async（非同步）

get_response(path, scope)

根據傳入的路徑、方法和請求標頭，返回 HTTP 回應。

參數	說明
path（路徑）	類型： str（字串）
scope（範圍）	類型： Scope（範圍）

原始程式碼位於 starlette/staticfiles.py

async def get_response(self, path: str, scope: Scope) -> Response:
    """
    Returns an HTTP response, given the incoming path, method and request headers.
    """
    if scope["method"] not in ("GET", "HEAD"):
        raise HTTPException(status_code=405)

    try:
        full_path, stat_result = await anyio.to_thread.run_sync(self.lookup_path, path)
    except PermissionError:
        raise HTTPException(status_code=401)
    except OSError as exc:
        # Filename is too long, so it can't be a valid static file.
        if exc.errno == errno.ENAMETOOLONG:
            raise HTTPException(status_code=404)

        raise exc

    if stat_result and stat.S_ISREG(stat_result.st_mode):
        # We have a static file to serve.
        return self.file_response(full_path, stat_result, scope)

    elif stat_result and stat.S_ISDIR(stat_result.st_mode) and self.html:
        # We're in HTML mode, and have got a directory URL.
        # Check if we have 'index.html' file to serve.
        index_path = os.path.join(path, "index.html")
        full_path, stat_result = await anyio.to_thread.run_sync(self.lookup_path, index_path)
        if stat_result is not None and stat.S_ISREG(stat_result.st_mode):
            if not scope["path"].endswith("/"):
                # Directory URLs should redirect to always end in "/".
                url = URL(scope=scope)
                url = url.replace(path=url.path + "/")
                return RedirectResponse(url=url)
            return self.file_response(full_path, stat_result, scope)

    if self.html:
        # Check for '404.html' if we're in HTML mode.
        full_path, stat_result = await anyio.to_thread.run_sync(self.lookup_path, "404.html")
        if stat_result and stat.S_ISREG(stat_result.st_mode):
            return FileResponse(full_path, stat_result=stat_result, status_code=404)
    raise HTTPException(status_code=404)

lookup_path（查找路徑）

lookup_path(path)

參數	說明
path（路徑）	類型： str（字串）

原始程式碼位於 starlette/staticfiles.py

def lookup_path(self, path: str) -> tuple[str, os.stat_result | None]:
    for directory in self.all_directories:
        joined_path = os.path.join(directory, path)
        if self.follow_symlink:
            full_path = os.path.abspath(joined_path)
        else:
            full_path = os.path.realpath(joined_path)
        directory = os.path.realpath(directory)
        if os.path.commonpath([full_path, directory]) != directory:
            # Don't allow misbehaving clients to break out of the static files
            # directory.
            continue
        try:
            return full_path, os.stat(full_path)
        except (FileNotFoundError, NotADirectoryError):
            continue
    return "", None

file_response（檔案回應）

file_response(
    full_path, stat_result, scope, status_code=200
)

參數	說明
full_path（完整路徑）	類型： PathLike（類路徑）
stat_result（狀態結果）	類型： stat_result（狀態結果）
scope（範圍）	類型： Scope（範圍）
status_code（狀態碼）	類型： int（整數） 預設值： 200

原始程式碼位於 starlette/staticfiles.py

def file_response(
    self,
    full_path: PathLike,
    stat_result: os.stat_result,
    scope: Scope,
    status_code: int = 200,
) -> Response:
    request_headers = Headers(scope=scope)

    response = FileResponse(full_path, status_code=status_code, stat_result=stat_result)
    if self.is_not_modified(response.headers, request_headers):
        return NotModifiedResponse(response.headers)
    return response

check_config（檢查設定） async（非同步）

check_config()

執行一次性設定檢查，確認 StaticFiles 確實指向一個目錄，以便我們可以發出明確的錯誤，而不是僅返回 404 回應。

原始程式碼位於 starlette/staticfiles.py

async def check_config(self) -> None:
    """
    Perform a one-off configuration check that StaticFiles is actually
    pointed at a directory, so that we can raise loud errors rather than
    just returning 404 responses.
    """
    if self.directory is None:
        return

    try:
        stat_result = await anyio.to_thread.run_sync(os.stat, self.directory)
    except FileNotFoundError:
        raise RuntimeError(f"StaticFiles directory '{self.directory}' does not exist.")
    if not (stat.S_ISDIR(stat_result.st_mode) or stat.S_ISLNK(stat_result.st_mode)):
        raise RuntimeError(f"StaticFiles path '{self.directory}' is not a directory.")

is_not_modified（未修改）

is_not_modified(response_headers, request_headers)

給定請求和回應標頭，如果可以返回 HTTP「未修改」回應，則返回 `True`。

參數	說明
response_headers（回應標頭）	類型： Headers（標頭）
request_headers（請求標頭）	類型： Headers（標頭）

原始程式碼位於 starlette/staticfiles.py

def is_not_modified(self, response_headers: Headers, request_headers: Headers) -> bool:
    """
    Given the request and response headers, return `True` if an HTTP
    "Not Modified" response could be returned instead.
    """
    try:
        if_none_match = request_headers["if-none-match"]
        etag = response_headers["etag"]
        if etag in [tag.strip(" W/") for tag in if_none_match.split(",")]:
            return True
    except KeyError:
        pass

    try:
        if_modified_since = parsedate(request_headers["if-modified-since"])
        last_modified = parsedate(response_headers["last-modified"])
        if if_modified_since is not None and last_modified is not None and if_modified_since >= last_modified:
            return True
    except KeyError:
        pass

    return False