請求中的檔案¶

🌐 AI 與人類共同完成的翻譯

此翻譯由人類指導的 AI 完成。🤝

可能會有對原意的誤解，或讀起來不自然等問題。🤖

你可以透過協助我們更好地引導 AI LLM來改進此翻譯。

英文版

你可以使用 File 定義由用戶端上傳的檔案。

Note

若要接收上傳的檔案，請先安裝 python-multipart。

將它加入你的專案：

$ uv add python-multipart

因為上傳的檔案是以「表單資料」送出的。

匯入 `File`¶

從 fastapi 匯入 File 與 UploadFile：

Python 3.10+

from typing import Annotated

from fastapi import FastAPI, File, UploadFile

app = FastAPI()


@app.post("/files/")
async def create_file(file: Annotated[bytes, File()]):
    return {"file_size": len(file)}


@app.post("/uploadfile/")
async def create_upload_file(file: UploadFile):
    return {"filename": file.filename}

🤓 Other versions and variants

Python 3.10+ - non-Annotated

Tip

Prefer to use the Annotated version if possible.

from fastapi import FastAPI, File, UploadFile

app = FastAPI()


@app.post("/files/")
async def create_file(file: bytes = File()):
    return {"file_size": len(file)}


@app.post("/uploadfile/")
async def create_upload_file(file: UploadFile):
    return {"filename": file.filename}

定義 `File` 參數¶

和 Body 或 Form 一樣的方式建立檔案參數：

Python 3.10+

from typing import Annotated

from fastapi import FastAPI, File, UploadFile

app = FastAPI()


@app.post("/files/")
async def create_file(file: Annotated[bytes, File()]):
    return {"file_size": len(file)}


@app.post("/uploadfile/")
async def create_upload_file(file: UploadFile):
    return {"filename": file.filename}

🤓 Other versions and variants

Python 3.10+ - non-Annotated

Tip

Prefer to use the Annotated version if possible.

from fastapi import FastAPI, File, UploadFile

app = FastAPI()


@app.post("/files/")
async def create_file(file: bytes = File()):
    return {"file_size": len(file)}


@app.post("/uploadfile/")
async def create_upload_file(file: UploadFile):
    return {"filename": file.filename}

Note

File 是直接繼承自 Form 的類別。

但請記住，當你從 fastapi 匯入 Query、Path、File 等時，它們其實是回傳特殊類別的函式。

Tip

要宣告檔案本文，必須使用 File，否則參數會被解讀為查詢參數或本文（JSON）參數。

檔案會以「表單資料」上傳。

如果你將路徑操作函式（path operation function）的參數型別宣告為 bytes，FastAPI 會替你讀取檔案，你會以 bytes 取得內容。

請注意，這表示整個內容會存放在記憶體中，適合小檔案。

但在許多情況下，使用 UploadFile 會更好。

使用 `UploadFile` 的檔案參數¶

將檔案參數型別設為 UploadFile：

Python 3.10+

from typing import Annotated

from fastapi import FastAPI, File, UploadFile

app = FastAPI()


@app.post("/files/")
async def create_file(file: Annotated[bytes, File()]):
    return {"file_size": len(file)}


@app.post("/uploadfile/")
async def create_upload_file(file: UploadFile):
    return {"filename": file.filename}

🤓 Other versions and variants

Python 3.10+ - non-Annotated

Tip

Prefer to use the Annotated version if possible.

from fastapi import FastAPI, File, UploadFile

app = FastAPI()


@app.post("/files/")
async def create_file(file: bytes = File()):
    return {"file_size": len(file)}


@app.post("/uploadfile/")
async def create_upload_file(file: UploadFile):
    return {"filename": file.filename}

使用 UploadFile 相較於 bytes 有數個優點：

你不必在參數的預設值使用 File()。
它使用「spooled」檔案：
- 檔案在記憶體中保存到某個大小上限，超過上限後會存到磁碟。
因此適合處理大型檔案（例如圖片、影片、大型二進位檔等），而不會耗盡記憶體。
你可以取得上傳檔案的中繼資料。
它提供一個file-like 的 async 介面。
它會提供實際的 Python SpooledTemporaryFile 物件，你可以直接傳給需要類檔案物件的其他函式或函式庫。

`UploadFile`¶

UploadFile 具有以下屬性：

filename：一個 str，為上傳的原始檔名（例如 myimage.jpg）。
content_type：一個 str，為內容類型（MIME type / media type）（例如 image/jpeg）。
file：一個 SpooledTemporaryFile（一個file-like 物件）。這是真正的 Python 檔案物件，你可以直接傳給期待「類檔案」物件的其他函式或函式庫。

UploadFile 有以下 async 方法。它們底層會呼叫對應的檔案方法（使用內部的 SpooledTemporaryFile）。

write(data)：將 data (str 或 bytes) 寫入檔案。
read(size)：讀取檔案的 size (int) 個位元組/字元。
seek(offset)：移動到檔案中的位元組位置 offset (int)。
- 例如，await myfile.seek(0) 會移到檔案開頭。
- 當你已經執行過 await myfile.read()，之後需要再次讀取內容時特別有用。
close()：關閉檔案。

由於這些都是 async 方法，你需要以 await 呼叫它們。

例如，在 async 的路徑操作函式中可這樣讀取內容：

contents = await myfile.read()

若是在一般的 def 路徑操作函式中，你可以直接存取 UploadFile.file，例如：

contents = myfile.file.read()

async 技術細節

當你使用這些 async 方法時，FastAPI 會在執行緒池中執行對應的檔案方法並等待結果。

Starlette 技術細節

FastAPI 的 UploadFile 直接繼承自 Starlette 的 UploadFile，但新增了一些必要部分，使其與 Pydantic 及 FastAPI 其他部分相容。

什麼是「表單資料」¶

HTML 表單（<form></form>）送到伺服器的資料通常使用一種「特殊」編碼，與 JSON 不同。

FastAPI 會從正確的位置讀取該資料，而不是當作 JSON。

技術細節

表單資料在不包含檔案時，通常使用媒體型別 application/x-www-form-urlencoded 編碼。

但當表單包含檔案時，會使用 multipart/form-data 編碼。若你使用 File，FastAPI 會知道要從請求本文的正確部分取得檔案。

若想進一步了解這些編碼與表單欄位，請參考 MDN web docs 的 POST。

Warning

你可以在一個路徑操作中宣告多個 File 與 Form 參數，但不能同時宣告預期以 JSON 接收的 Body 欄位，因為此請求的本文會使用 multipart/form-data 而不是 application/json。

這不是 FastAPI 的限制，而是 HTTP 協定本身的規範。

可選的檔案上傳¶

可透過一般型別註解並將預設值設為 None 使檔案成為可選：

Python 3.10+

from typing import Annotated

from fastapi import FastAPI, File, UploadFile

app = FastAPI()


@app.post("/files/")
async def create_file(file: Annotated[bytes | None, File()] = None):
    if not file:
        return {"message": "No file sent"}
    else:
        return {"file_size": len(file)}


@app.post("/uploadfile/")
async def create_upload_file(file: UploadFile | None = None):
    if not file:
        return {"message": "No upload file sent"}
    else:
        return {"filename": file.filename}

🤓 Other versions and variants

Python 3.10+ - non-Annotated

Tip

Prefer to use the Annotated version if possible.

from fastapi import FastAPI, File, UploadFile

app = FastAPI()


@app.post("/files/")
async def create_file(file: bytes | None = File(default=None)):
    if not file:
        return {"message": "No file sent"}
    else:
        return {"file_size": len(file)}


@app.post("/uploadfile/")
async def create_upload_file(file: UploadFile | None = None):
    if not file:
        return {"message": "No upload file sent"}
    else:
        return {"filename": file.filename}

`UploadFile` 搭配額外中繼資料¶

你也可以在 UploadFile 上搭配 File()，例如用來設定額外的中繼資料：

Python 3.10+

from typing import Annotated

from fastapi import FastAPI, File, UploadFile

app = FastAPI()


@app.post("/files/")
async def create_file(file: Annotated[bytes, File(description="A file read as bytes")]):
    return {"file_size": len(file)}


@app.post("/uploadfile/")
async def create_upload_file(
    file: Annotated[UploadFile, File(description="A file read as UploadFile")],
):
    return {"filename": file.filename}

🤓 Other versions and variants

Python 3.10+ - non-Annotated

Tip

Prefer to use the Annotated version if possible.

from fastapi import FastAPI, File, UploadFile

app = FastAPI()


@app.post("/files/")
async def create_file(file: bytes = File(description="A file read as bytes")):
    return {"file_size": len(file)}


@app.post("/uploadfile/")
async def create_upload_file(
    file: UploadFile = File(description="A file read as UploadFile"),
):
    return {"filename": file.filename}

多檔案上傳¶

可以同時上傳多個檔案。

它們會同屬於以「表單資料」送出的同一個表單欄位。

要這麼做，將型別宣告為 bytes 或 UploadFile 的 list：

Python 3.10+

from typing import Annotated

from fastapi import FastAPI, File, UploadFile
from fastapi.responses import HTMLResponse

app = FastAPI()


@app.post("/files/")
async def create_files(files: Annotated[list[bytes], File()]):
    return {"file_sizes": [len(file) for file in files]}


@app.post("/uploadfiles/")
async def create_upload_files(files: list[UploadFile]):
    return {"filenames": [file.filename for file in files]}


@app.get("/")
async def main():
    content = """
<body>
<form action="/files/" enctype="multipart/form-data" method="post">
<input name="files" type="file" multiple>
<input type="submit">
</form>
<form action="/uploadfiles/" enctype="multipart/form-data" method="post">
<input name="files" type="file" multiple>
<input type="submit">
</form>
</body>
    """
    return HTMLResponse(content=content)

🤓 Other versions and variants

Python 3.10+ - non-Annotated

Tip

Prefer to use the Annotated version if possible.

from fastapi import FastAPI, File, UploadFile
from fastapi.responses import HTMLResponse

app = FastAPI()


@app.post("/files/")
async def create_files(files: list[bytes] = File()):
    return {"file_sizes": [len(file) for file in files]}


@app.post("/uploadfiles/")
async def create_upload_files(files: list[UploadFile]):
    return {"filenames": [file.filename for file in files]}


@app.get("/")
async def main():
    content = """
<body>
<form action="/files/" enctype="multipart/form-data" method="post">
<input name="files" type="file" multiple>
<input type="submit">
</form>
<form action="/uploadfiles/" enctype="multipart/form-data" method="post">
<input name="files" type="file" multiple>
<input type="submit">
</form>
</body>
    """
    return HTMLResponse(content=content)

你會如宣告所示，收到由 bytes 或 UploadFile 組成的 list。

技術細節

你也可以使用 from starlette.responses import HTMLResponse。

FastAPI 為了讓你（開發者）更方便，提供與 starlette.responses 相同的內容作為 fastapi.responses。但大多數可用的回應類型其實直接來自 Starlette。

多檔案上傳且包含額外中繼資料¶

同樣地，即使對 UploadFile，你也可以用 File() 設定額外參數：

Python 3.10+

from typing import Annotated

from fastapi import FastAPI, File, UploadFile
from fastapi.responses import HTMLResponse

app = FastAPI()


@app.post("/files/")
async def create_files(
    files: Annotated[list[bytes], File(description="Multiple files as bytes")],
):
    return {"file_sizes": [len(file) for file in files]}


@app.post("/uploadfiles/")
async def create_upload_files(
    files: Annotated[
        list[UploadFile], File(description="Multiple files as UploadFile")
    ],
):
    return {"filenames": [file.filename for file in files]}


@app.get("/")
async def main():
    content = """
<body>
<form action="/files/" enctype="multipart/form-data" method="post">
<input name="files" type="file" multiple>
<input type="submit">
</form>
<form action="/uploadfiles/" enctype="multipart/form-data" method="post">
<input name="files" type="file" multiple>
<input type="submit">
</form>
</body>
    """
    return HTMLResponse(content=content)

🤓 Other versions and variants

Python 3.10+ - non-Annotated

Tip

Prefer to use the Annotated version if possible.

from fastapi import FastAPI, File, UploadFile
from fastapi.responses import HTMLResponse

app = FastAPI()


@app.post("/files/")
async def create_files(
    files: list[bytes] = File(description="Multiple files as bytes"),
):
    return {"file_sizes": [len(file) for file in files]}


@app.post("/uploadfiles/")
async def create_upload_files(
    files: list[UploadFile] = File(description="Multiple files as UploadFile"),
):
    return {"filenames": [file.filename for file in files]}


@app.get("/")
async def main():
    content = """
<body>
<form action="/files/" enctype="multipart/form-data" method="post">
<input name="files" type="file" multiple>
<input type="submit">
</form>
<form action="/uploadfiles/" enctype="multipart/form-data" method="post">
<input name="files" type="file" multiple>
<input type="submit">
</form>
</body>
    """
    return HTMLResponse(content=content)

小結¶

使用 File、bytes 與 UploadFile 來宣告請求中要上傳的檔案，這些檔案會以表單資料送出。

請求中的檔案¶

匯入 File¶

定義 File 參數¶

使用 UploadFile 的檔案參數¶

UploadFile¶

什麼是「表單資料」¶

可選的檔案上傳¶

UploadFile 搭配額外中繼資料¶

多檔案上傳¶

多檔案上傳且包含額外中繼資料¶

小結¶

匯入 `File`¶

定義 `File` 參數¶

使用 `UploadFile` 的檔案參數¶

`UploadFile`¶

`UploadFile` 搭配額外中繼資料¶