我在慢慢還債了，目前更新到 D18

網站能對帳了，還要能在別的機器上開起來。這堂課把三個環境講清楚：改程式的開發、產出畫面資產的建置、以及現場只靠 Python 的開站。三者共用同一份資料契約，但 現場機器不該被要求再裝前端工具鏈。 搞混這件事，就會出現「Linux 上要先 npm install 才能看 DRC」這種把入口變專案的事故。

原則只有一句：畫面資產可以整個換掉；階層與上傳這兩堆 JSON 的數量與內容，建置過程不准默默動到。

  開發機                         建置                         現場開站
  Node 22 + 開發伺服器            編成 JS / CSS                只要 Python
  改外框、各頁、讀檔整理            不准清空 JSON                 unzip → 開站
  兩個行程、同一堆檔               前後各數一次檔數               瀏覽器貼網址

一、三個角色，三種需求

改畫面的人需要 Node 22、套件、開發伺服器。他改的是外框、各頁、讀檔整理、樣式。他看資料的方式，應與現場相同：讀執行目錄裡的那兩堆檔。

只負責讓同事看得到的人，需要 Python 3.9 以上，以及一份已經建好的執行目錄加開站腳本。他不該需要知道 React 是什麼。unzip、開站、瀏覽器貼上網址。失敗時他能查的，也只是目錄裡有沒有檔、埠有沒有被占。

把網站送到那台機器的人，需要一個最小包：開站腳本、首頁、打包後的 JS／CSS、兩堆 JSON。原始碼、node_modules、說明文件都可以不進包。包愈小，愈不會有人在現場「順便改一下原始碼」卻沒人會建。

Day 14 把建置與執行切開，今天是把切開執行到清單。開發可以熱重載；開站不可以依賴熱重載。現場沒有人會為了看一張表而開兩個終端。

二、開發：兩個行程，同一份事實

開發時開兩樣東西：小伺服器根在執行目錄，負責清單與 JSON；前端開發伺服器負責畫面，並把清單與兩堆檔的請求轉到那台小伺服器。你改 CSS 立刻看見，你改 JSON 刷新就看見。不要為開發另做 mock 專案表。mock 會讓契約長出第二張臉，上線當天才發現檔名規則與假資料不同。

開發機是 Windows、現場是 Linux 時，有三件事必須在開發期就當 Linux 想。檔名大小寫：讀檔整理那支程式的引入路徑必須與真實檔名一致。百分號檔名：取檔路徑必須編碼。路徑分隔：父親欄位裡的目錄字元，解析時要兩種都能切。就緒檢查腳本就是為這三件事存在的，不要等拷到 Linux 才第一次踩。

改讀檔整理或畫面後，本地至少走一次 Day 16 的最小集：大廳有卡、階層有列、Block 有葉子。這不是完整測試，是避免「我只改了顏色卻把資料包欄位改壞」。資料包是縫，縫一裂，每一頁都會怪。

三、建置：產出資產，並數 JSON

建置會把原始碼編成帶雜湊檔名的 JS 與 CSS，連同首頁放到執行目錄。關鍵設定是：不要清空整個執行目錄。清掉資產可以；清掉 design 與 uploads 不行。額外的保險是建置前後各數一次 JSON 個數，數量一變就拒絕結束，並說清楚是哪一堆變了。

這看起來偏執，直到第一次有人用預設的「打包前清空輸出」把一個月的上傳刪成零。備份若還在，只是驚嚇；備份不在，就是事故。偏執比事故便宜。

建置機的 Node 版本鎖在 22。現場不需要這個版本。請不要因為現場有一個舊 Node，就在現場建。現場只開站。若現場必須改畫面，那是把現場誤當成開發機，流程已經歪了。把改動帶回有工具鏈的地方建，再把資產送回去。

四、開站：最小目錄，一個埠

開站腳本把執行目錄當根，列出清單，送靜態檔。印四行：現在服務哪個目錄、清單網址、首頁、JSON 在哪兩個子目錄。現場同事第一次開站，靠的是這四行，不是這篇教程。埠被占用要明白說，不要只丟系統錯誤。

最小樹：

  開站腳本
  dist/
    index.html
    assets/     打包後的畫面
    design/     階層
    uploads/    上傳

把這棵樹打成壓縮包即可搬遷。來源對應關係要在打包時檢查：沒有畫面資產就拒絕打包，以免送到現場才發現只有 JSON。地圖檔（原始碼對應表）預設可不進包，除非要在現場除錯瀏覽器。包小，拷得快，也少一份洩漏原始結構的檔。

開站後用清單網址確認兩堆檔名在。再用瀏覽器走最小集。現場若只能內網，把主機綁在可達的位址，不要假設每個人都會 ssh 做埠轉發。入口是給團隊的，不是給你自己的 localhost。

五、資料在現場怎麼長

新專案：加一份階層檔，刷新。新 run：加一份上傳，刷新。不必重開站。小伺服器每次清單都重掃目錄。這是 JSON 方案在部署上的紅利——沒有遷移、沒有寫入介面、沒有重載設定。

換畫面版本：換掉首頁與 assets，保留兩堆 JSON。先數檔數，再換資產，再數一次。數量不對就停。舊資產檔名帶雜湊，換新後舊檔名會 404，這正常，清掉舊 assets 即可。不要連 design 一起清。

權限：執行目錄要讓開站的人讀得到 JSON。不要把上傳目錄設成只有某一套流水線能寫、開站帳號卻讀不到，那種現場會呈現「清單是空的」。空清單先查權限與路徑，再查產品。

六、用檢查清單代替記憶

開發機：Node 22、Python 3.9、兩堆目錄在、清單能回檔名、帶百分號的上傳取得到、引入路徑大小寫正確。可加一次含建置的檢查，確認 JSON 數量在建置前後不變。

打包機：建置成功、資產裡有 JS 與 CSS、兩堆目錄在、壓縮包內含開站腳本與上述東西、不含 node_modules。

現場：Python 能開、埠開、清單有檔、最小集走得通、刷新仍通。

這三張單子過了，部署就算完成。它不保證 DRC 正確——那是對帳的事——它保證 同一個入口在三個地方仍是同一個入口。

現場常見的失敗比較土。開錯目錄：腳本預設執行目錄，人卻在上一層開，清單空。埠被占：錯誤要寫出埠號，換一個再開。瀏覽器快取舊的 JS：雜湊檔名通常能避免，若有人用了很兇的快取代理，清單已設不要存。JSON 在 Windows 看得到、Linux 404：百分號與大小寫。這四個，就緒檢查與打包腳本能擋前半；後半要靠 Day 16 的編碼契約。

換畫面版本時請當儀式做：先數上傳個數，記下來；換 assets 與 index；再數一次；打開清單對檔名；走一顆認得的 block，確認 DRC 仍是那個 12。儀式五分鐘。省略儀式、直接清整個 dist，是這座平台唯一真正危險的操作。把這句寫進 README 也不為過。

開發與現場資料可以不是同一份。現場有真專案，開發可以用最小集。契約必須同一份。最小集裡的鍵名、日期格式、父親寫法，都要能代表現場。否則開發過關、現場一丟真檔就全滅。

Lab — count JSON, then python build.py

改過 src/（例如 Day 17 的 Notes）之後，Vite 上看到的還不是現場那份。現場吃的是 dist/index.html + dist/assets/。

在 repo root：

# Windows PowerShell
(Get-ChildItem dist/design/*.json).Count
(Get-ChildItem dist/uploads/*.json).Count

# Linux / macOS
# ls dist/design/*.json | wc -l
# ls dist/uploads/*.json | wc -l

python build.py

build.py 會呼叫 npm run build（需要 Node 22），然後再數一次 JSON。數量變了會 REFUSING 離開——這是保護，不是你建失敗。若你剛用 Day 16 多丟了一個 design 檔，count 本來就會變；那是預期，不要清 dist/design 去「修」。

Build 完：

1. 停 Vite 也沒關係。只開 python serve.py --dir dist --port 8080，用 http://127.0.0.1:8080/ 走最小集（Home → 階層 → block）。
2. 若做了 Notes：正式包也應看得到 #/project/.../notes。沒做就跳過。
3. 可選：python scripts/pack_deploy.py 看最小包裡有 serve.py、index.html、assets/、兩堆 JSON，沒有 node_modules。

Done when： 畫面資產換了，兩堆 JSON 的個數與 build 前相同（或你明確知道自己加了檔）。永遠不要手動清空整個 dist/。