FastAPI 基礎概念：安裝與環境設定（pip、Poetry、uvicorn）

簡介

在開始使用 FastAPI 前，先把開發環境佈置好是最重要的步驟。正確的套件管理與執行工具不只讓專案更易於維護，也能避免因相依衝突而產生的錯誤。
本單元將說明三個核心工具：

1. pip – Python 官方的套件安裝器。
2. Poetry – 現代化的相依管理與封裝工具，讓虛擬環境、版本鎖定變得簡單。
3. uvicorn – 高效能的 ASGI 伺服器，負責啟動 FastAPI 應用。

掌握這些工具後，你就能在任何作業系統上快速建立、測試與部署 FastAPI 專案，為後續的路由、依賴注入與資料驗證奠定穩固基礎。

---

核心概念

1. 使用 pip 安裝 FastAPI 與 Uvicorn

pip 是最直接的套件安裝方式，適合剛接觸 Python 的新手或是想在單一腳本中快速測試的情境。

# 建立專案資料夾
mkdir my_fastapi_demo && cd my_fastapi_demo

# 建立虛擬環境（推薦使用 venv）
python -m venv .venv
# 啟動虛擬環境
# Windows
.\.venv\Scripts\activate
# macOS / Linux
source .venv/bin/activate

# 安裝 FastAPI 與 Uvicorn
pip install fastapi uvicorn

小技巧：在 requirements.txt 中記錄相依，日後部署只要 pip install -r requirements.txt 即可。

# requirements.txt 範例
fastapi==0.111.0
uvicorn[standard]==0.27.0

2. Poetry：更完整的相依與封裝管理

Poetry 讓專案的相依、版本鎖定與發行流程全部集中在一個工具裡，避免手動編輯 requirements.txt 帶來的錯誤。

2.1 安裝 Poetry

官方推薦使用單行腳本安裝：

curl -sSL https://install.python-poetry.org | python3 -
# 確認安裝成功
poetry --version

注意：若使用 Windows，建議改用 PowerShell 執行 iwr https://install.python-poetry.org -UseBasicParsing | python -。

2.2 建立新專案與相依

# 建立一個名為 fastapi-demo 的 Poetry 專案
poetry new fastapi-demo
cd fastapi-demo

# 加入 FastAPI 與 Uvicorn 為相依
poetry add fastapi uvicorn[standard]

此時會產生 pyproject.toml，其中包含：

[tool.poetry]
name = "fastapi-demo"
version = "0.1.0"
description = ""
authors = ["Your Name <you@example.com>"]

[tool.poetry.dependencies]
python = "^3.9"
fastapi = "^0.111.0"
uvicorn = {extras = ["standard"], version = "^0.27.0"}

2.3 虛擬環境與執行

Poetry 會自動為每個專案管理虛擬環境，使用以下指令即可進入：

poetry shell   # 進入 Poetry 虛擬環境
# 或者直接執行指令
poetry run uvicorn app.main:app --reload

3. Uvicorn：啟動 FastAPI 應用

uvicorn 是符合 ASGI 規範的伺服器，支援 HTTP/1.1、WebSocket 以及自動重載（--reload）功能，特別適合開發階段。

3.1 基本啟動指令

uvicorn app.main:app --host 0.0.0.0 --port 8000

• app.main:app 表示 module app/main.py 中的 app 變數（FastAPI 實例）。
• --reload 會在檔案變更時自動重啟伺服器，僅在開發環境使用。

3.2 使用 --workers 提升效能

在生產環境，建議使用多工作執行緒：

uvicorn app.main:app --workers 4

uvicorn 內建的 gunicorn 兼容層（uvicorn.workers.UvicornWorker）亦可搭配 gunicorn 使用，提供更完整的進程管理。

gunicorn app.main:app -k uvicorn.workers.UvicornWorker --workers 4

---

常見陷阱與最佳實踐

常見情況	可能的問題	解決方案
忘記啟動虛擬環境	全域安裝套件，導致版本衝突	始終使用 source .venv/bin/activate（或 poetry shell）
pip 安裝時出現權限錯誤	系統全域目錄無寫入權限	使用 --user 或 建議 使用 Poetry 管理相依
Uvicorn 無法找到 app 變數	模組路徑或變數名稱寫錯	確認 app/main.py 中 app = FastAPI() 並使用正確的 module:variable 格式
開發時忘記加 --reload	每次修改程式都需要手動重啟	在 pyproject.toml 或 Makefile 中加入 uvicorn ... --reload 為預設指令
相依版本不一致	部署環境與開發環境套件版本不同	使用 Poetry lock (poetry lock) 產生 poetry.lock，部署時執行 poetry install --no-root

最佳實踐

1. 使用 Poetry 管理相依：自動產生鎖檔，確保每個環境使用相同版本。
2. 將 uvicorn 加入 scripts：在 pyproject.toml 中設定快捷指令，減少打字錯誤。

[tool.poetry.scripts]
start = "uvicorn app.main:app --reload"

執行 poetry run start 即可啟動開發伺服器。

3. 環境變數分離：使用 .env 檔或 python-dotenv 管理資料庫連線、API 金鑰等敏感資訊，避免硬編碼。

# .env 範例
DATABASE_URL=postgresql://user:pass@localhost/dbname
SECRET_KEY=super-secret-key

4. CI/CD 整合：在 GitHub Actions、GitLab CI 中加入 poetry install 與 uvicorn 測試指令，確保每次合併都能順利通過。

# .github/workflows/ci.yml 範例
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-python@v5
        with:
          python-version: "3.11"
      - name: Install Poetry
        run: curl -sSL https://install.python-poetry.org | python3 -
      - name: Install dependencies
        run: poetry install
      - name: Run tests
        run: poetry run pytest

---

實際應用場景

場景	為何選擇 FastAPI + Poetry + Uvicorn
微服務	輕量、非阻塞的 ASGI 架構，配合 Docker 多容器部署非常順手。
資料科學 API	FastAPI 自帶的自動文件產生（Swagger UI）讓模型服務快速上線，Poetry 保證相依一致性。
即時聊天 / WebSocket	Uvicorn 原生支援 WebSocket，開發者只需在路由中加入 WebSocket 類別即可。
企業內部工具	透過 Poetry 的封裝功能，可將 API 包裝成可發佈的 wheel 檔，並在內部 PyPI 伺服器上管理版本。
Serverless (AWS Lambda)	只需要把 app 物件包裝成 Mangum 介面，Poetry 產生的 requirements.txt 可直接用於 Lambda 層。

---

總結

• pip 為最直接的套件安裝方式，適合快速驗證概念。
• Poetry 提供相依鎖定、虛擬環境與封裝的完整解決方案，是長期維護專案的首選。
• uvicorn 作為高效能的 ASGI 伺服器，負責啟動與管理 FastAPI 應用，配合 --reload、--workers 等參數即可滿足開發與生產需求。

透過本篇的步驟，你已經能在本機或 CI 環境中 完整建立、執行、測試 FastAPI 專案。接下來，只要把注意力轉向路由設計、資料驗證與依賴注入，就能一步步打造出可擴充、效能優異的現代 Web API。祝開發順利！