爲什麼要容器化？¶
在開發和部署應用時，我們常常會遇到“在我電腦上能運行”但“在你電腦上不行”的問題，這就是環境不一致導致的。Docker容器化技術能解決這個問題——它把你的應用和所有依賴打包成一個獨立的“盒子”，不管在什麼機器上，打開這個盒子就能運行你的應用，就像打開一個罐頭一樣簡單。
FastAPI是一個高性能、易上手的Python API框架，用它開發的服務，配合Docker容器化後部署會更方便、更一致。接下來，我們一步步來實現。
一、準備工作：先寫一個最簡單的FastAPI應用¶
1. 安裝Python和依賴¶
首先確保你的電腦上安裝了Python（推薦3.7+版本）。然後創建一個項目文件夾，比如叫fastapi-docker-demo，在裏面新建一個main.py文件，這是FastAPI應用的入口文件。
2. 編寫FastAPI代碼¶
在main.py中輸入以下代碼：
from fastapi import FastAPI
app = FastAPI()
@app.get("/")
def read_root():
return {"Hello": "World"} # 訪問根路徑返回Hello World
@app.get("/items/{item_id}")
def read_item(item_id: int, q: str = None):
return {"item_id": item_id, "q": q} # 帶參數的示例接口
這段代碼創建了一個FastAPI應用，包含兩個接口：
- 根路徑/返回JSON數據{"Hello": "World"}
- 帶參數的路徑/items/{item_id}，接收整數item_id和可選字符串q
3. 生成依賴文件¶
在項目根目錄下，打開命令行，運行：
pip install fastapi uvicorn # 安裝FastAPI和Uvicorn（Uvicorn是FastAPI推薦的運行服務器）
pip freeze > requirements.txt # 生成依賴文件，記錄需要安裝的包
此時項目目錄結構應該是這樣的：
fastapi-docker-demo/
├── main.py
└── requirements.txt
二、用Docker打包FastAPI應用¶
1. 什麼是Dockerfile？¶
Dockerfile是一個文本文件，裏面包含了構建Docker鏡像的所有指令。我們需要用它告訴Docker“如何把FastAPI應用打包成一個鏡像”。
2. 編寫Dockerfile¶
在項目根目錄下新建一個Dockerfile（沒有後綴名），輸入以下內容：
# 1. 基礎鏡像：使用Python 3.9的精簡版鏡像
FROM python:3.9-slim
# 2. 設置工作目錄（容器內的工作路徑）
WORKDIR /app
# 3. 複製依賴文件到容器內（先複製requirements.txt是爲了利用Docker緩存，加快構建速度）
COPY requirements.txt .
# 4. 安裝依賴
RUN pip install --no-cache-dir -r requirements.txt
# 5. 複製當前目錄的所有文件到容器內的/app目錄
COPY . .
# 6. 容器啓動時執行的命令：啓動Uvicorn服務器
CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]
每一行的作用解釋：
- FROM python:3.9-slim：從Docker倉庫拉取Python 3.9的精簡版鏡像（體積小，適合生產環境）
- WORKDIR /app：在容器內創建並進入/app目錄，後續操作都在這個目錄下
- COPY requirements.txt .：把本地的requirements.txt複製到容器的/app目錄
- RUN pip install ...：安裝依賴文件裏的包，--no-cache-dir是爲了不緩存依賴，減少鏡像體積
- COPY . .：把本地所有文件（除了.dockerignore裏的）複製到容器的/app目錄
- CMD ["uvicorn", ...]：當容器啓動時，執行uvicorn命令啓動FastAPI服務，--host 0.0.0.0表示允許外部訪問，--port 8000指定端口
3. 忽略不需要的文件（可選）¶
如果項目裏有__pycache__、.git等文件，Docker會一起打包，導致鏡像變大。可以創建.dockerignore文件，內容如下：
__pycache__
*.pyc
*.pyo
*.pyd
.git
.gitignore
三、構建Docker鏡像¶
1. 構建鏡像命令¶
在項目根目錄下（確保Docker已經安裝），打開命令行，執行：
docker build -t my-fastapi-app .
-t my-fastapi-app：給鏡像起個名字my-fastapi-app（可以自定義）.：表示Dockerfile在當前目錄下
執行後，Docker會自動按照Dockerfile的步驟構建鏡像。如果一切順利，最後會顯示Successfully built [鏡像ID]。
2. 檢查鏡像是否構建成功¶
運行以下命令，查看本地鏡像列表：
docker images
你應該能看到剛纔創建的my-fastapi-app鏡像。
四、運行Docker容器¶
1. 啓動容器¶
執行以下命令啓動容器，同時把容器的8000端口映射到主機的8000端口（這樣才能從瀏覽器訪問）：
docker run -p 8000:8000 my-fastapi-app
-p 8000:8000：端口映射，格式是主機端口:容器端口my-fastapi-app：要運行的鏡像名稱
啓動後，你會看到類似以下日誌：
INFO: Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)
這說明服務已經啓動，並且監聽在容器的8000端口（通過--host 0.0.0.0設置的）。
五、測試服務是否正常運行¶
1. 訪問API接口¶
打開瀏覽器，訪問http://localhost:8000，你應該能看到返回{"Hello": "World"}。
或者用命令行工具curl測試：
curl http://localhost:8000
輸出：{"Hello":"World"}
2. 訪問自動生成的API文檔¶
FastAPI自帶Swagger UI和ReDoc，方便調試接口。訪問：
http://localhost:8000/docs
這裏可以看到所有接口的詳細說明，點擊“Try it out”還能直接測試接口參數。
六、常見問題和解決方法¶
1. 端口被佔用怎麼辦？¶
如果啓動時報錯Bind to address 0.0.0.0:8000 failed，說明8000端口被其他程序佔用。解決方法：
- 換一個端口（比如8001）：修改Dockerfile中的CMD爲uvicorn main:app --host 0.0.0.0 --port 8001，然後重新構建鏡像，啓動時用-p 8001:8001
- 停止佔用端口的程序：在Windows用netstat -ano | findstr 8000，找到PID後用taskkill /PID [PID] /F結束進程；在Linux/Mac用lsof -i :8000找到進程ID後kill
2. 如何修改代碼後重新部署？¶
每次修改代碼後，需要重新構建鏡像並啓動容器：
# 先停止之前的容器（如果沒後臺運行）
docker stop [容器ID]
# 重新構建鏡像
docker build -t my-fastapi-app .
# 重新啓動容器
docker run -p 8000:8000 my-fastapi-app
七、總結¶
通過Docker容器化部署FastAPI，你可以：
1. 確保開發、測試、生產環境一致，避免“在我電腦上能跑”的問題
2. 快速遷移服務，只需複製鏡像文件
3. 隔離應用依賴，讓部署更輕量
後續還可以進一步優化，比如：
- 使用Docker Compose管理多個服務（比如FastAPI+數據庫）
- 配置Nginx反向代理，用HTTPS
- 部署到雲平臺（如阿里雲、AWS、Google Cloud）的容器服務
現在你已經掌握了FastAPI+Docker的基礎部署流程，可以開始把你的API服務封裝成容器，實現一鍵部署啦！