【適合初學者】使用 Python 安全讀取 YAML 檔案的方法｜safe_load 使用方式與錯誤對策徹底解析

1. 如何在 Python 中讀取 YAML？｜本文概要與目標讀者

想在 Python 中處理 YAML 的您

• 將 Web 應用程式或腳本的設定檔外部化
• 想在 Python 中解析Docker Compose 或 Kubernetes的設定檔
• 想用 YAML 管理機器學習框架的參數

本文可學到的事

• YAML 檔案的基本結構與特點
• Python 中的讀取方法（safe_load() 的用法）
• 常見錯誤及其對策
• 多重文件讀取或設定檔的實務範例

目標讀者

• 想在 Python 中使用 YAML 的初學者～中級者
• 需要處理設定檔的開發者
• 對 PyYAML 的用法感到不安的人
• 想詳細了解 safe_load() 或錯誤對應的人

2. YAML 是什麼？｜與 JSON 的差異與特點簡單比較

YAML 是什麼？

與 JSON 的差異

YAML 的優點

• 直觀的寫法：類似 Python 的縮排，容易掌握結構
• 可寫註解：方便在設定檔中添加補充說明
• 不冗長：不需要 JSON 般的中括弧或雙引號
• 對人類友好：非工程師也能輕鬆閱讀與修改

YAML 的使用場合

• Docker Compose（docker-compose.yml）
• Kubernetes 的設定檔（Pod 或 Service 的定義）
• CI/CD 工具（GitHub Actions、GitLab CI 等）
• 機器學習函式庫（PyTorch Lightning 或 Hydra 等）
• Web 應用程式或腳本的設定檔

3. 使用 Python 處理 YAML 的準備｜PyYAML 的安裝

什麼是 PyYAML？

PyYAML 的安裝方法

pip install pyyaml

建議使用虛擬環境

# 虛擬環境的建立
python -m venv venv

# 啟用虛擬環境
# Windows 的情況
venv\Scripts\activate
# macOS/Linux 的情況
source venv/bin/activate

# 安裝 PyYAML
pip install pyyaml

安裝確認方法

import yaml
print(yaml.__version__)

4. 【基本】使用 Python 讀取 YAML 檔案的方法（safe_load 的用法）

最基本的讀取方法：safe_load()

範例 YAML 檔案（config.yaml）

app:
  name: SampleApp
  version: 1.0.0
debug: true
servers:
  - host: localhost
    port: 8000
  - host: example.com
    port: 443

Python 中的讀取程式碼範例

import yaml

with open('config.yaml', 'r', encoding='utf-8') as f:
    config = yaml.safe_load(f)

print(config)

輸出範例（Python 的字典形式）

{
  'app': {'name': 'SampleApp', 'version': '1.0.0'},
  'debug': True,
  'servers': [
    {'host': 'localhost', 'port': 8000},
    {'host': 'example.com', 'port': 443}
  ]
}

open()函數中指定編碼很重要

小提示：with語法的活用

5. safe_load 和 load 的差異｜Python 中 YAML 讀取的注意事項

safe_load() 和 load() 有什麼不同？

safe_load() 的特點（安全的讀取）

import yaml

with open('config.yaml', 'r', encoding='utf-8') as f:
    data = yaml.safe_load(f)

• 應使用的基本函數
• 安全性高（不讀取任意的 Python 物件）
• 限制於基本資料型（字典、列表、字串、數值等）
• 嘗試讀取未知的型別或物件時會發生錯誤

load() 的特點（靈活但有風險）

import yaml

with open('config.yaml', 'r', encoding='utf-8') as f:
    data = yaml.load(f, Loader=yaml.FullLoader)

• 能更靈活地解釋 YAML
• 可還原 Python 物件（例如：函數、類別實例等）
• 由於安全性風險，必須指定 Loader

yaml.YAMLLoadWarning: calling yaml.load() without Loader=... is deprecated

Loader 的種類（安全性和靈活性的差異）

結論：通常使用 safe_load()

6. 常見錯誤及其解決方法｜Python YAML 讀取的陷阱

YAML 讀取時絆倒的原因是什麼？

1. 縮排錯誤導致的語法錯誤

範例：有縮排錯誤的 YAML

user:
  name: Alice
    age: 30

錯誤訊息範例：

yaml.scanner.ScannerError: mapping values are not allowed here

解決方法：

• 以2～4 個空格統一縮排（不要使用 Tab）
• 子元素要比父元素縮排更深

2. 檔案編碼導致字元亂碼

錯誤範例：

UnicodeDecodeError: 'cp932' codec can't decode byte...

解決方法：

with open('config.yaml', 'r', encoding='utf-8') as f:
    data = yaml.safe_load(f)

• 明確指定 encoding='utf-8' 即可解決
• 在 Windows 環境中特別容易忘記的要點

3. 檔案路徑錯誤／不存在的檔案

錯誤範例：

FileNotFoundError: [Errno 2] No such file or directory: 'config.yaml'

解決方法：

• 確認是否以絕對路徑或正確的相對路徑指定
• 檢查檔案名稱或副檔名是否有輸入錯誤
• 確認檔案是否位於與腳本相同的目錄

4. 使用 safe_load 讀取的結果為None

範例：

# 這個檔案中沒有任何設定

結果：

data = yaml.safe_load(f)
print(data)  # 輸出: None

解決方法：

• 確認檔案中是否有記述有效的 YAML 資料
• 僅有註解或空白時，返回 None 是正常的行為

5. 過於複雜的 YAML 結構解析錯誤

解決方法：

• 逐步確認語法（以小區段為單位驗證）
• 建議捕捉 yaml.YAMLError 例外並確認詳細訊息

try:
    with open('config.yaml', 'r', encoding='utf-8') as f:
        data = yaml.safe_load(f)
except yaml.YAMLError as e:
    print(f"YAML 讀取錯誤: {e}")

總結：發生錯誤時不要慌張，檢查語法和環境

• 縮排是否正確（是否未使用 Tab）
• 檔案的編碼是否為 UTF-8
• 檔案是否存在
• YAML 的內容是否正確記述

7. 應用：讀取多個文件的 YAML 文件的方法（safe_load_all）

YAML 可以包含多個文件在單一文件中

多個文件的 YAML 檔案範例（multi.yaml）

# 伺服器設定1
---
server:
  host: localhost
  port: 8080

# 伺服器設定2
---
server:
  host: example.com
  port: 443

yaml.safe_load_all() 的使用方法

import yaml

with open('multi.yaml', 'r', encoding='utf-8') as f:
    documents = yaml.safe_load_all(f)
    for doc in documents:
        print(doc)

執行結果（輸出範例）：

{'server': {'host': 'localhost', 'port': 8080}}
{'server': {'host': 'example.com', 'port': 443}}

注意 safe_load() 的差異

也可以將讀取的文件轉換為列表

with open('multi.yaml', 'r', encoding='utf-8') as f:
    documents = list(yaml.safe_load_all(f))

注意事項：並非所有 YAML 檔案都對應多個文件

8. 【補足】使用 YAML 作為設定檔案時的要點

為什麼 YAML 適合用作設定檔案？

• Web 應用程式的環境設定（生產／開發／測試）
• 機器學習的超參數設定
• 腳本的行為切換
• API 金鑰等外部依賴資訊的管理（※機密資訊的管理需注意）

實用的 YAML 設定檔案範例

app:
  name: MyApp
  mode: production

logging:
  level: INFO
  file: logs/app.log

database:
  host: localhost
  port: 5432
  user: admin
  password: secret

活用巢狀結構的設定階層化

env:
  dev:
    db: dev-db.local
    debug: true
  prod:
    db: prod-db.server
    debug: false

能以註解明示意圖

# 應用程式的模式設定（dev, test, production 其中之一）
mode: production

執行時讀取 YAML 的程式碼範例（應用）

import yaml

with open('settings.yaml', 'r', encoding='utf-8') as f:
    config = yaml.safe_load(f)

app_name = config['app']['name']
mode = config['app']['mode']
db_host = config['database']['host']

注意事項：機密資訊的處理需十分注意

• 使用 .gitignore 防止提交到儲存庫
• 與 .env 檔案等結合，從 YAML 只進行參照
• 套用加密或存取限制

9. 常見問題（FAQ）

Q1. YAML 和 JSON，在 Python 中哪個比較好處理？

Q2. yaml.load() 不能使用嗎？

Q3. 讀取的 YAML 內容變成空的（None）是為什麼？

# 這個檔案還沒有設定

Q4. YAML 檔案中可以像變數一樣重複使用值嗎？

default: &defaults
  timeout: 30
  retries: 3

service1:
  <<: *defaults
  host: service1.local

service2:
  <<: *defaults
  host: service2.local

Q5. 在 Windows 環境中日文會出現亂碼。該怎麼辦？

with open('config.yaml', 'r', encoding='utf-8') as f:
    data = yaml.safe_load(f)

Q6. 如果 YAML 檔案分成多個設定區塊要怎麼讀取？

---
app: App1
port: 3000
---
app: App2
port: 4000

with open('multi.yaml', 'r', encoding='utf-8') as f:
    for doc in yaml.safe_load_all(f):
        print(doc)

10. 總結｜掌握Python中的YAML讀取

回顧YAML讀取從基礎到應用的內容

• PyYAML的安裝：要在Python中處理YAML，首先需要 pip install pyyaml。
• 基本的讀取：yaml.safe_load() 就能安全且簡單地將YAML讀取為字典或清單。
• 錯誤對策：縮排或編碼錯誤是常見的問題。語法檢查和encoding='utf-8'很重要。
• load()的差異：如果重視安全性，應該使用 safe_load()。load()必須指定適當的Loader。
• 多重文件對應：使用safe_load_all()，就能靈活處理單一檔案內的多個設定區塊。
• 作為設定檔案的實用性：可讀性與彈性優異的YAML，是Python專案中的設定管理最佳選擇。

今後步驟：更多活用YAML

• 寫入YAML檔案：使用yaml.dump() 來自動產生設定檔案
• 與JSON的相互轉換：在與Web API或外部服務聯動時很方便
• 與.env檔案或環境變數併用：建構高安全性的設定管理手法
• 設定的自動載入化：在應用程式啟動時，動態讀取依環境而定的設定檔案