科技 · 實用指南
Python 找不到時區？先分辨資料缺失與鍵名錯誤，再改設定
使用實際報錯的直譯器，比較控制鍵與目標時區，並在新程序中驗證部署的資料來源。
例外訊息提到 UTC，不代表應該換掉 UTC。先確認失敗程序能否存取時區資料，再核對所需的鍵名是否存在。
1. 固定失敗的執行環境與目標鍵
保留完整追蹤訊息及鍵名，包括大小寫與底線。使用同一執行檔、服務帳號、容器或虛擬環境診斷，記錄 sys.executable、sys.version、zoneinfo.TZPATH 與 os.environ.get('PYTHONTZPATH')。另一個互動式終端機能執行，只是比較結果，不能證明應用程式已修復。
也要在該環境檢查 importlib.util.find_spec('tzdata')。某個直譯器能找到的套件，另一個可能沒有。不要為了順利啟動而變更業務時區、關閉時區支援，或以固定偏移取代地區規則。
2. 比較控制鍵與真正需要的鍵
在新程序中先試 ZoneInfo('UTC')，再試原本所需的精確鍵名。兩者都失敗時，先查資料是否可用；UTC 成功而目標失敗時，查拼字、已部署的資料集及是否包含該鍵。這只是診斷分支，不表示所有 UTC 失敗都有相同原因。
如果業務確實使用紐約，核對 IANA 鍵 America/New_York。我們的隔離實驗中，即使 tzdata 可用，America/NewYork 與 UTC+8 仍失敗。不要從答案隨意複製一個可用城市，否則可能改變歷史偏移或日光節約時間規則。
3. 證明部署環境可用的資料來源
zoneinfo 先搜尋設定的系統目錄，再嘗試 Python 的 tzdata 套件。Windows 安裝通常需要該套件，精簡 Linux 映像也可能缺少系統檔案。決定由哪個相依項目提供資料，並納入可重現的應用程式或映像建置，不要只在某個終端機臨時修補。
若採用套件資料，透過應用程式實際直譯器呼叫獲准的安裝工具，例如該 Python 執行檔加上 -m pip install tzdata，並寫入正常的相依清單。受管理環境應更新建置設定，不使用 sudo 或繞過旗標。若採用系統資料，由映像或作業系統維護者佈建支援的時區資料集。
4. 採用隔離比較，別修改線上快取
我們在 Linux 的 CPython 3.12.14 執行四組子程序：停用 site 套件但保留系統路徑時，UTC 與 America/New_York 成功；再將 PYTHONTZPATH 設為空時，兩者失敗；正常載入 site 並使用空路徑時，兩者透過套件後備來源成功；相對路徑則產生 InvalidTZPathWarning，該實驗沒有留下可用的系統路徑。
這說明「未安裝套件」與「程序找不到資料」不是同一觀察，也不代表本機測試了 Windows。空路徑只用於受控的套件後備測試，未決定資料版本政策前不要部署。reset_tzpath 不會清除既有 ZoneInfo 物件，因此驗收應啟動新程序，而不是清理線上服務快取。
5. 驗證原啟動流程與季節規則
完成有依據的最小修復後，依原啟動方式重新啟動。載入未變更的目標鍵，執行原先失敗的操作並保存結果。地區時區也應比較代表性的冬夏日期。我們只使用套件的實驗中，紐約 2026 年 1 月 15 日為 UTC−05:00，7 月 15 日為 UTC−04:00；這不是完整的歷史時區測試。
記錄執行檔、部署映像或環境、選用的資料相依項目、精確鍵名與前後輸出。若新終端機正常而服務仍失敗，請在服務內部蒐集相同清單。若已知資料可用但鍵仍失敗，查明名稱與資料版本；停止猜測城市或向無關環境反覆安裝。
