Sync fastapi docs from 50113da1 on 2026-09-11

2026-09-11 04:00:08 +00:00
parent 632909b5f6
commit 818066b271
739 changed files with 4974 additions and 17395 deletions
@@ -105,40 +105,36 @@ Docker 是用來建立與管理容器映像與容器的主要工具之一。

 ### 套件需求 { #package-requirements }

-你的應用通常會把「套件需求」放在某個檔案中。
+當你使用 `uv` 管理專案時，它的直接相依會宣告在 `pyproject.toml` 中，而精確解析出的版本會儲存在 `uv.lock`。

-這主要取決於你用什麼工具來安裝那些需求。
-
-最常見的方式是準備一個 `requirements.txt` 檔案，逐行列出套件名稱與版本。
-
-當然，你會用與在 [關於 FastAPI 版本](versions.md) 中讀到的相同概念，來設定版本範圍。
-
-例如，你的 `requirements.txt` 可能像這樣：
-
-```
-fastapi[standard]>=0.113.0,<0.114.0
-pydantic>=2.7.0,<3.0.0
-```
-
-接著你通常會用 `pip` 來安裝這些套件相依，例如：
+你可以用以下指令加入你的應用需要的套件：

 <div class="termy">

 ```console
-$ pip install -r requirements.txt
+$ uv add "fastapi[standard]" pydantic
 ---> 100%
-Successfully installed fastapi pydantic
 ```

 </div>

 /// note | 注意

-還有其他格式與工具可以用來定義與安裝套件相依。
+下面的 Dockerfile 會在容器內使用 `pip`。你可以從你的 uv 專案匯出鎖定的相依，轉成它預期的 `requirements.txt` 格式：
+
+<div class="termy">
+
+```console
+$ uv export --format requirements-txt --no-dev --no-emit-project --output-file requirements.txt
+```
+
+</div>
+
+產生的 `requirements.txt` 是用於容器建置的匯出檔。請繼續使用 `uv add` 管理相依，並在 `uv.lock` 變更時重新產生它。

 ///

-### 建立 FastAPI 程式碼 { #create-the-fastapi-code }
+### 建立 **FastAPI** 程式碼 { #create-the-fastapi-code }

 * 建立一個 `app` 目錄並進入。
 * 建立一個空的 `__init__.py` 檔案。
@@ -372,7 +368,7 @@ $ docker run -d --name mycontainer -p 80:80 myimage

 你也可以前往 [http://192.168.99.100/redoc](http://192.168.99.100/redoc) 或 [http://127.0.0.1/redoc](http://127.0.0.1/redoc)（或等效的、使用你的 Docker 主機）。

-你會看到另一種自動產生的文件（由 [ReDoc](https://github.com/Rebilly/ReDoc) 提供）：
+你會看到另一種自動產生的文件（由 [ReDoc](https://github.com/Redocly/redoc) 提供）：

 ![ReDoc](https://fastapi.tiangolo.com/img/index/index-02-redoc-simple.png)

@@ -5,7 +5,7 @@
 <div class="termy">

 ```console
-$ fastapi deploy
+$ uv run fastapi deploy

 Deploying to FastAPI Cloud...

@@ -24,9 +24,9 @@ CLI 會自動偵測你的 FastAPI 應用並將其部署到雲端。若你尚未

 **[FastAPI Cloud](https://fastapicloud.com)** 由 **FastAPI** 的作者與團隊打造。

-它以最少的心力，精簡化建立、部署與存取 API 的流程。
+它以最少的心力，精簡化**建立**、**部署**與**存取** API 的流程。

-它把使用 FastAPI 開發應用的優異開發體驗，延伸到將它們部署到雲端。🎉
+它把使用 FastAPI 開發應用的優異**開發體驗**，延伸到將它們**部署**到雲端。🎉

 它也會為你處理部署應用時多數需要面對的事項，例如：

@@ -52,7 +52,7 @@ FastAPI 採用建立 Python 網頁框架與伺服器的標準 <abbr title="Async

 有數個替代方案，包括：

-* [Uvicorn](https://www.uvicorn.dev/)：高效能 ASGI 伺服器。
+* [Uvicorn](https://uvicorn.dev)：高效能 ASGI 伺服器。
 * [Hypercorn](https://hypercorn.readthedocs.io/)：支援 HTTP/2 與 Trio 等功能的 ASGI 伺服器。
 * [Daphne](https://github.com/django/daphne)：為 Django Channels 打造的 ASGI 伺服器。
 * [Granian](https://github.com/emmett-framework/granian)：針對 Python 應用的 Rust HTTP 伺服器。
@@ -73,14 +73,14 @@ FastAPI 採用建立 Python 網頁框架與伺服器的標準 <abbr title="Async

 但你也可以手動安裝 ASGI 伺服器。

-請先建立並啟用一個 [虛擬環境](../virtual-environments.md)，接著再安裝伺服器程式。
+將伺服器應用程式加入你的專案。

 例如，安裝 Uvicorn：

 <div class="termy">

 ```console
-$ pip install "uvicorn[standard]"
+$ uv add "uvicorn[standard]"

 ---> 100%
 ```
@@ -95,7 +95,7 @@ $ pip install "uvicorn[standard]"

 其中包含 `uvloop`，它是 `asyncio` 的高效能替代實作，可大幅提升並行效能。

-當你用 `pip install "fastapi[standard]"` 安裝 FastAPI 時，也會一併取得 `uvicorn[standard]`。
+當你用像 `uv add "fastapi[standard]"` 這樣加入 FastAPI 時，也會一併取得 `uvicorn[standard]`。

 ///

@@ -106,7 +106,7 @@ $ pip install "uvicorn[standard]"
 <div class="termy">

 ```console
-$ uvicorn main:app --host 0.0.0.0 --port 80
+$ uv run uvicorn main:app --host 0.0.0.0 --port 80

 <span style="color: green;">INFO</span>:     Uvicorn running on http://0.0.0.0:80 (Press CTRL+C to quit)
 ```
@@ -9,19 +9,19 @@
 * 記憶體
 * 啟動前的前置作業

-到目前為止，依照文件中的教學，你大多是透過 `fastapi` 指令啟動一個執行 Uvicorn 的伺服器程式，且只跑單一處理序。
+到目前為止，依照文件中的教學，你大多是透過 `fastapi` 指令啟動一個執行 Uvicorn 的**伺服器程式**，且只跑**單一處理序**。

-在部署應用時，你通常會希望有一些處理序的複製來善用多核心，並能處理更多請求。
+在部署應用時，你通常會希望有一些**處理序的複製**來善用**多核心**，並能處理更多請求。

 如同前一章關於 [部署概念](concepts.md) 所示，你可以採用多種策略。

-這裡會示範如何使用 `fastapi` 指令或直接使用 `uvicorn` 指令，搭配 Uvicorn 的工作處理序（worker processes）。
+這裡會示範如何使用 `fastapi` 指令或直接使用 `uvicorn` 指令，搭配 **Uvicorn** 的**工作處理序**（worker processes）。

 /// note

 如果你使用容器（例如 Docker 或 Kubernetes），我會在下一章說明更多：[容器中的 FastAPI - Docker](docker.md)。

-特別是，在 **Kubernetes** 上執行時，你多半會選擇不要使用 workers，而是每個容器只跑一個 **Uvicorn 單一處理序**。我會在該章節中進一步說明。
+特別是，在 **Kubernetes** 上執行時，你多半會**不要**使用 workers，而是每個容器只跑一個 **Uvicorn 單一處理序**。我會在該章節中進一步說明。

 ///

@@ -86,7 +86,7 @@ $ <font color="#4E9A06">fastapi</font> run --workers 4 <u style="text-decoration
 <div class="termy">

 ```console
-$ uvicorn main:app --host 0.0.0.0 --port 8080 --workers 4
+$ uv run uvicorn main:app --host 0.0.0.0 --port 8080 --workers 4
 <font color="#A6E22E">INFO</font>:     Uvicorn running on <b>http://0.0.0.0:8080</b> (Press CTRL+C to quit)
 <font color="#A6E22E">INFO</font>:     Started parent process [<font color="#A1EFE4"><b>27365</b></font>]
 <font color="#A6E22E">INFO</font>:     Started server process [<font color="#A1EFE4">27368</font>]
@@ -109,7 +109,7 @@ $ uvicorn main:app --host 0.0.0.0 --port 8080 --workers 4

 這裡唯一新增的選項是 `--workers`，告訴 Uvicorn 要啟動 4 個工作處理序。

-你也會看到它顯示每個處理序的 **PID**，`27365` 是父處理序（這是**處理序管理器**），另外每個工作處理序各有一個：`27368`、`27369`、`27370`、`27367`。
+你也會看到它顯示每個處理序的 **PID**，`27365` 是父處理序（這是**處理序管理器**），另外每個工作處理序各有一個：`27368`、`27369`、`27370` 和 `27367`。

 ## 部署概念 { #deployment-concepts }