M12　設定檔的世界

1設定檔無處不在 Configuration everywhere

打開這個課程網站自己的倉庫，設定檔比課程內容還多：

格式你都學過了。分別在於：每個工具只認自己那一套鍵名，而且各自有些自己的規矩。

2VS Code：准許註解的 JSON VS Code: JSON with comments

這個課程倉庫的 .vscode/settings.json（節錄）：

{
  // Markdown：Tab 鍵展開本課的 snippets
  "[markdown]": {
    "editor.tabCompletion": "onlySnippets",
    "editor.wordWrap": "on"
  },
  "liveServer.settings.port": 5501
}

M8 說過 JSON 不准寫註解，用 json.loads 讀它果然報錯：

JSONDecodeError: Expecting property name enclosed in double quotes: line 2 column 3 (char 4)

因為 VS Code 的設定檔不是嚴格的 JSON，而是 JSONC（JSON with Comments）：准許 // 和 /* */ 註解。給人改的設定檔需要註解，所以 VS Code 放寬了規則。

VS Code 編輯這些檔案時，會用 JSON Schema（M10）檢查：鍵名打錯，下面會出現波浪線；輸入時會自動列出可用的設定。這就是 M10 那套方法在日常工具裏的樣子。

3GitHub Actions：YAML 的陷阱 GitHub Actions

GitHub Actions 讓 GitHub 在你 push 之後自動執行檢查。設定寫在 .github/workflows/ 裏的 YAML 檔：

name: 檢查課程網站
on:
  push:
    branches: [main]
jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4          # 取出倉庫的內容
      - uses: actions/setup-python@v5      # 安裝 Python
        with:
          python-version: "3.12"
      - run: python tools/build.py --check

flowchart LR
    E["on：push 到 main"] --> J["job：check<br/>runs-on: ubuntu-latest"]
    J --> S1["step 1<br/>取出倉庫"]
    S1 --> S2["step 2<br/>安裝 Python 3.12"]
    S2 --> S3["step 3<br/>build.py --check"]
    classDef e fill:#f1f1ef,stroke:#d3d1cb,color:#37352f
    classDef s fill:#ffffff,stroke:#d3d1cb,color:#37352f
    class E,J e
    class S1,S2,S3 s

這類檔案常見兩個 M9 的陷阱：

• python-version: 3.10 會變成 3.1（M9 的 1.10）。GitHub 會去找 Python 3.1，結果失敗或者裝錯版本。這是 GitHub Actions 最常見的錯誤之一，所以上面寫成 "3.12"，版本號一律加引號；
• on: 這個鍵，用 PyYAML 讀入會變成 True（M9 的 on）。GitHub 自己的讀法沒有問題，但你用 Python 讀 workflow 檔時，要寫 wf[True]，不是 wf["on"]。

4docker-compose：端口要加引號 docker-compose: quote your ports

Docker 用 compose.yaml 描述要執行哪些服務：

services:
  web:
    image: nginx:1.27
    ports:
      - "8080:80"        # 本機 8080 → 容器 80
      - "2222:22"        # 本機 2222 → 容器 22（SSH）

ports 的寫法是「本機端口:容器端口」。不加引號會怎樣？用 PyYAML 實測：

冒號後面的數字小於 60，就會被當成六十進制（M9 的 9:30）。這是 PyYAML 和其他跟舊版 YAML 1.1 的工具的讀法；YAML 1.2 已經沒有六十進制（見 M9 的「YAML 1.1 與 1.2」）。但你無法保證每個讀這份檔的程式都跟 1.2，所以端口一律加引號，不用逐個判斷。

5Markdown 的 frontmatter Markdown frontmatter

這個課程的每一個單元，都是一個 Markdown 檔，開頭有一段用 --- 包住的 YAML，叫做 frontmatter：

---
title: 設定檔的世界
time: 約 45 分鐘
goals:
  - 認出常見工具的設定檔用哪種格式、放在哪裏；
---

## 設定檔無處不在 …

網站產生器（包括本課的 tools/build.py）和 Obsidian 都這樣用：frontmatter 放這份文件的資料（標題、日期、標籤），下面才是內容。讀它的方法很簡單：用 --- 切開，中間那段交給 yaml.safe_load。本課的建置腳本就是這樣做的。

6Claude Code 的設定 Claude Code settings

Claude Code 的設定是 JSON，分三層，越下面越優先：

公司或學校的管理員還可以在這三層之上加一層受管理的設定（managed settings），它優先於這三層，個人和專案的設定都蓋不過它。

最常改的是權限，例如准許它執行哪些命令、禁止它讀哪些檔案：

{
  "permissions": {
    "allow": ["Bash(python3 tools/build.py:*)"],
    "deny": ["Read(./.env)"]
  }
}

這三層的分法，在很多工具裏都見到：個人設定、專案設定、只在自己電腦上的設定。密碼、API key 這類秘密，永遠不要寫進會放進 Git 的設定檔；要用的話，放在不入 Git 的檔案或環境變數裏。

7安全地修改設定檔 Editing config files safely

設定檔寫錯了，工具可能啟動不了，也可能靜靜地用錯的設定執行（M9 的挪威）。改之前、改之後，花一分鐘檢查：

flowchart LR
    A["先 commit"] --> B["只改一處"]
    B --> C["用程式讀"]
    C -->|"報錯"| B
    C -->|"讀得到"| D["印出型別"]
    D --> E["讓工具使用"]
    classDef s fill:#ffffff,stroke:#d3d1cb,color:#37352f
    class A,B,C,D,E s

1. 先 commit（git-course 的習慣）：改壞了，一句命令就能退回；
2. 一次只改一處：出問題時，你知道是哪一處；
3. 用程式讀一次：json.loads、yaml.safe_load、tomllib.loads，語法錯誤立即現形；
4. 印出改了的值和型別：抓 M9 那種「合法但猜錯」的錯誤；有 schema 的話，跑一次驗證（M10）；
5. 最後才讓工具使用新的設定。

連這一頁也不例外：本頁開頭的 frontmatter，學習目標裏有一句提到 python-version: 3.10。那個「冒號＋空格」令 YAML 把整句讀成一個 dict，建置當場失敗。修法正是 M9 的規則：整句加引號。之後建置腳本加了一道檢查，學習目標不是文字就清楚地報出是哪一句。

8容易混淆 Easily confused

9動手：設定檔巡禮 Hands-on: a tour of config files

1. 下載 m12-config-tour.ipynb 和 m12-configs.zip，放進 python-course 資料夾；
2. 執行 uv run jupyter lab，打開 notebook，逐格執行。

zip 裏有小書店網站的五個設定檔：VS Code 設定、GitHub Actions workflow、docker-compose、一篇有 frontmatter 的網誌文章、Claude Code 設定。每個檔都藏了一個這單元講過的問題。你要逐個讀入、找出問題、修好，並寫一個函式，一次檢查全部設定檔。