目錄

1. 前言
2. 開發 FastAPI 專案
3. 建立 Dockerfile
4. 撰寫 docker-compose.yml
5. 建立 .env 檔案（可選）
6. 部署與測試
7. 總結

1. 前言

FastAPI 是一個高效能、現代化的 Python Web 框架，特別適合開發 API。
搭配 Docker + Docker Compose，可以讓部署快速且穩定。

這篇教學將帶你一步步從開發到容器化部署。

2. 開發 FastAPI 專案

2.1 建立專案結構

mkdir fastapi-docker-demo
cd fastapi-docker-demo
mkdir app

專案結構會是這樣：

fastapi-docker-demo/
├── app/
│   └── main.py
├── requirements.txt
├── Dockerfile
└── docker-compose.yml

2.2 撰寫 FastAPI 程式碼

建立 app/main.py：

python複製編輯# app/main.py

from fastapi import FastAPI
import uvicorn
import os

app = FastAPI()

@app.get("/")
async def root():
    return {"message": "Hello from FastAPI + Docker!"}

if __name__ == "__main__":
    uvicorn.run(
        "app.main:app",
        host="0.0.0.0",
        port=8000,
        reload=os.getenv("RELOAD", "false").lower() == "true"
    )

• 這裡會根據環境變數 RELOAD 判斷是否啟用 reload，方便開發和生產環境切換！

2.3 建立 requirements.txt

pip install fastapi uvicorn
pip freeze > requirements.txt

內容會像這樣：

fastapi
uvicorn

3. 建立 Dockerfile

在專案根目錄建立 Dockerfile：

# 使用官方 Python 映像
FROM python:3.12-slim

# 設定工作目錄
WORKDIR /app

# 安裝套件
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# 複製應用程式
COPY ./app ./app

# 預設執行指令
CMD ["python", "app/main.py"]

這樣 Docker build 出來的 container 會直接用 python app/main.py 啟動！

4. 撰寫 docker-compose.yml

建立 docker-compose.yml：

yaml複製編輯# docker-compose.yml

version: "3.9"

services:
  fastapi-app:
    build: .
    container_name: fastapi_app
    ports:
      - "8000:8000"
    environment:
      - RELOAD=false
    restart: always

說明：

• ports: "8000:8000"：把 container 的 8000 port 映射到本機。
• environment: RELOAD=false：生產環境關閉 hot reload。

5. 建立 .env 檔案（可選）

可以建立 .env 檔案來管理變數：

RELOAD=false

然後在 docker-compose.yml 中加入：

env_file:
  - .env

這樣就不用每次都寫 environment 了，管理上更乾淨！

6. 部署與測試

6.1 本機開發模式

如果是本地測試（不走 Docker），直接執行：

python app/main.py

因為 reload=True 是靠環境變數控制，可以靈活開啟。

6.2 使用 Docker Compose 部署

一鍵啟動！

docker compose up -d

啟動後打開瀏覽器，訪問：

http://localhost:8000/

會看到回傳：

{"message": "Hello from FastAPI + Docker!"}

API 文件自動生成：

• Swagger UI: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc

7. 總結

這篇教學帶你從零開始，建立一個 FastAPI 專案並用 Docker 容器化，配合 Docker Compose 簡單部署。
用這種方式開發、測試、部署 API，非常快速且適合團隊協作或雲端部署。

專案完整結構圖

fastapi-docker-demo/
├── app/
│   └── main.py
├── requirements.txt
├── Dockerfile
├── docker-compose.yml
└── .env (optional)