在 Cloudflare Pages 上的純靜態網站
無需建置步驟。編輯檔案 → 推送到 main → Cloudflare Pages 自動部署。快速、便宜，而且你再也不需要與工具鏈奮戰。
為何選擇純靜態（決策理由）
- 零建置/CI 負擔；修改兩行程式碼的修正只需要 30 秒就能部署。
- 沒有框架綁定或重寫的成本。「新增，不要重寫」是原則。
- 整個網站可搜尋、可除錯、且一目瞭然。
- 接受的取捨：需要更多手動 DOM 程式碼。在小到中等規模時，這是值得的。
儲存庫 + 部署
- 一個 GitHub 儲存庫 → Cloudflare Pages 專案，在推送到
main時自動部署。 - Pages 服務儲存庫根目錄。漂亮的 URL：
/mi-cuenta.html會在/mi-cuenta被提供服務。 - Functions（無伺服器）位於
/functions目錄（請參閱supabase-backend）。
部署儀式（每次部署都要做）
- 編輯檔案。
- 驗證 JS 可編譯——絕對不要推送壞掉的行內 JS。擷取行內的
<script>區塊，並對每個區塊執行vm.compileFunction；對於.js/.cjs檔案則使用node --check。請參閱reference/verify-inline.cjs。 - 快取無效化資產：執行
node .claude/cache-bust.cjs——它會在 HTML 中每個assets/**/*.css|js的引用上加上?v=<git-short-hash>標記，並寫入version.json。請參閱reference/cache-bust.cjs。 - 更新版本標記（單一事實來源在一個 JS 檔案中，並在頁尾低調顯示）並記錄它。請參閱
project-continuity了解版本控制方案。 - 提交（使用專案的語言撰寫描述性訊息）並加上共同作者標記，然後推送到
main。 - 驗證上線狀態：使用
curl請求已部署的資產，確認新的版本標記，並且version.json與資產的?v=參數相符（它們必須一致，否則自動重新載入器會陷入迴圈）。Cloudflare 的機器人防護會封鎖一般的爬蟲 → 請使用瀏覽器的 User-Agent。
.claude/通常會加入.gitignore，因此快取無效化/驗證腳本會保留在本機（它們在你的機器上於建置時執行，而非在儲存庫中）。
快取無效化 + 自動重新載入（終結「頁面沒更新」的電話遊戲）
兩層機制，都在 reference/ 目錄中：
cache-bust.cjs——每次部署時重新為所有資產引用加上?v=<git hash>標記，以便瀏覽器重新擷取已變更的 CSS/JS，同時寫入version.json = {"v":"<hash>"}。- 自動重新載入器（
reference/auto-reload.js）——一個小型的腳本，包含在每個頁面中，它會讀取自身載入時的?v=參數，輪詢/version.json（以no-store方式提供服務），並在偵測到新部署時：在使用者返回分頁時重新載入（安全時機），在使用者正在觀看時顯示一個單擊「Actualizar」的橫幅，並且絕不打斷正在進行的輸入動作（window.__noAutoReload可選擇退出，適用於考試或結帳流程）。初始載入的注意事項： 第一次使用時，使用者需要手動重新整理一次以載入重新載入器；之後就會自動運作。
透過 _headers 提供最新的標記：
/version.json
Cache-Control: no-store, max-age=0
安全標頭（位於儲存庫根目錄的 _headers）
永遠設定：Content-Security-Policy（將 script-src/frame-src/connect-src 限制為確切的 CDN 網域 + 你的 Supabase URL + wss 用於即時功能）、X-Frame-Options: DENY、X-Content-Type-Options: nosniff、Referrer-Policy: strict-origin-when-cross-origin、Permissions-Policy、Strict-Transport-Security。已遇到的陷阱：嵌入影片 iframe 需要在 frame-src 中加入播放器網域，否則瀏覽器會默默封鎖它。
可重複使用的 CSS 慣例
- 基於代碼的主題系統，使用 CSS 變數；一個
data-theme="dark"的重新對應加上一個共用的localStorage鍵，讓主題能在不同頁面/分頁之間同步。 - 深色模式：通過對比度還不夠——你還需要可見的圖層層級（背景 < 表面 < 卡片），並加上淺色階梯與陰影，否則它看起來會是平的。
- 永遠不要硬編碼
white/顏色；使用代碼讓主題能夠回應。 - 不要破壞全域的
.btn/.btn-primary；在作用域內覆寫就好。
此技能包含的檔案
reference/cache-bust.cjs——資產標記器 + version.json 寫入器。reference/auto-reload.js——部署自動重新載入器（放入一個全域載入的 JS 檔案中）。reference/verify-inline.cjs——在部署前編譯檢查行內<script>區塊。reference/headers-example——一個起始用的_headers檔案。