SAE 部署 Python 應用完整指南：依賴管理與專案結構最佳實踐

新浪雲引擎（SAE）作為國內早期 PaaS 平台，雖有諸多限制，但文檔完善、上手容易，適合部署中小型 Python 應用。本文詳細說明如何在 SAE 上管理第三方依賴、打包部署，並建立可維護的專案結構。

核心痛點與解決方案

SAE 預裝了 Flask 等常用套件，但專案常需額外依賴。早期需手動複製套件至專案目錄，現透過 saecloud 工具可像 pip 一樣安裝依賴：

saecloud install -r requirements.txt

此命令將套件安裝至 site-packages 目錄，部署前可打包成 ZIP：

cd site-packages/
zip -r ../site-packages.zip .

WSGI 入口配置依賴載入

在 index.wsgi 中加入路徑：

import os, sys
root = os.path.dirname(__file__)

# 二選一，推薦使用 ZIP 方式
sys.path.insert(0, os.path.join(root, 'site-packages'))
sys.path.insert(0, os.path.join(root, 'site-packages.zip'))

依賴分離策略：避免冗餘

區分「SAE 未預裝」與「本地開發需求」兩類依賴：

# 僅安裝 SAE 缺少的套件到專案目錄
pip install -r requirements.txt

# 維護 SAE 預裝套件清單（僅本地開發用）
saecloud install -r requirements-dev.txt

如此 requirements.txt 只有真正需打包的套件，避免 Flask 等預裝套件重複佔用空間。

推薦專案目錄結構

LICENSE
Makefile
README.md
requirements-dev.txt    # SAE 預裝套件（本地開發用）
requirements.txt        # 需打包部署的套件
site-packages/          # 本地安裝目錄（不提交）
site/                   # Web 應用主目錄
    index.wsgi
    main.py
    config.yaml
    site-packages.zip   # 打包後的依賴（部署用）

.gitignore 設定

/site-packages
/site/site-packages.zip
/site/index.wsgic

自動化部署：Makefile

編寫 Makefile 整合安裝依賴、打包、部署流程，實現一鍵部署。

實戰建議

• 優先使用 site-packages.zip 減少檔案數量，加快上傳速度
• 定期同步 requirements-dev.txt 與 SAE 官方預裝清單
• 善用 SAE 環境變數區分開發/生產環境配置
• 監控配額使用情況，避免超額導致服務中斷