首次部署到 Cloudflare Workers｜手把手

這份是第一次從零部署用。後續更新流程在 DEPLOY.md。

前置確認

你已經有的（從 hbs-vault 經驗）：

✅ Cloudflare 帳號
✅ Node.js + npm
✅ wrangler CLI（如果沒登入過：npx wrangler login）
✅ git

如果上面有缺，先 Google 安裝。下面假設都有了。

步驟 1｜跑 build 確認本地內容 OK

cd /c/Users/alber/Desktop/AI_Playground/mental-models-vault
python _scripts/prep_for_quartz.py

預期輸出：46 個檔案、10 個 dataview block 轉換。輸出在 _build/quartz-content/，這是 Quartz 直接讀的乾淨 markdown。

步驟 2｜建立獨立的 Quartz 專案

跟 hbs-vault 用同套（Quartz）但獨立的目錄：

cd /c/Users/alber/Desktop/AI_Playground
git clone https://github.com/jackyzha0/quartz.git mental-models-quartz
cd mental-models-quartz
npm install

npm install 大約 1-2 分鐘。

步驟 3｜初始化 Quartz

npx quartz create

它會問幾個問題：

問題	選
Choose how to initialize the content	Empty Quartz
Choose how Quartz should resolve links	Shortest path

完成後 content/ 目錄會被建立（空的）。

步驟 4｜把 vault build 結果指向 Quartz

Option A｜symlink（推薦，自動同步）

cd /c/Users/alber/Desktop/AI_Playground/mental-models-quartz
rm -rf content
# Git Bash on Windows 可能需要管理員權限
ln -s ../mental-models-vault/_build/quartz-content content

如果 symlink 不能用（Windows 開發者模式沒開），跳到 Option B：

Option B｜手動複製

cd /c/Users/alber/Desktop/AI_Playground/mental-models-quartz
rm -rf content/*
cp -r ../mental-models-vault/_build/quartz-content/* content/

Option B 每次更新都要重新 cp，但比較不會遇到 Windows symlink 權限問題。建議先用 B，跑通後再考慮 A。

步驟 5｜設定 Quartz config

編輯 mental-models-quartz/quartz.config.ts，找到 configuration 區塊改成：

configuration: {
  pageTitle: "心智模型工具箱 · Mental Models Vault",
  pageTitleSuffix: "",
  enableSPA: true,
  enablePopovers: true,
  analytics: null,            // 之後想加再說
  locale: "zh-TW",
  baseUrl: "mental-models.albertckchien.workers.dev",  // CF Worker URL，先寫，CF 建好後對齊
  ignorePatterns: ["private", "templates", ".obsidian", "_build"],
  defaultDateType: "created",
  theme: {
    fontOrigin: "googleFonts",
    cdnCaching: true,
    typography: {
      header: "Noto Serif TC",
      body: "Noto Serif TC",
      code: "JetBrains Mono",
    },
    colors: {
      lightMode: {
        light: "#faf8f1",
        lightgray: "#e5e1d8",
        gray: "#b8b1a3",
        darkgray: "#4e4842",
        dark: "#2b2823",
        secondary: "#8b6f47",
        tertiary: "#d4a373",
        highlight: "rgba(143, 159, 169, 0.15)",
      },
      darkMode: {
        light: "#161618",
        lightgray: "#393639",
        gray: "#646464",
        darkgray: "#d4d4d4",
        dark: "#ebebec",
        secondary: "#d4a373",
        tertiary: "#8b6f47",
        highlight: "rgba(212, 163, 115, 0.15)",
      },
    },
  },
},

顏色我抓的是「文藝復古」配色（暖米白 + 焦糖棕）。不喜歡可以再調，或直接 copy hbs-vault 的色票。

步驟 6｜本地預覽

cd /c/Users/alber/Desktop/AI_Playground/mental-models-quartz
npx quartz build --serve

跑起來後開瀏覽器：http://localhost:8080

檢查重點：

✅ 首頁能看到 README 的內容
✅ 左側 Explorer 列出所有資料夾
✅ 隨便點一條常駐工具（例如「逆向思考」）能正確 render
✅ Wikilinks 點下去能跳轉
✅ 使用指南內的 Dataview query 結果已經是靜態 markdown table/list（不是空白也不是 raw 程式碼）

有問題就停下來修。沒問題就進步驟 7。

按 Ctrl + C 關掉 dev server。

步驟 7｜建立 CF Workers 專案

兩種做法：

Option A｜用 wrangler 一條指令建（推薦）

cd /c/Users/alber/Desktop/AI_Playground/mental-models-quartz
npx wrangler init mental-models

它會問：

Use TypeScript? → Yes
What type of application? → "Hello World" Worker (using fetch)
Use git for version control? → No（我們已經有 git）

Option B｜CF dashboard 手動建

到 https://dash.cloudflare.com → Workers & Pages → Create application → Create Worker → 命名 mental-models。

兩個都 OK。

步驟 8｜設定 wrangler.toml

在 mental-models-quartz/ 目錄編輯 wrangler.toml（沒有就新建）：

name = "mental-models"
compatibility_date = "2026-01-01"
account_id = "YOUR_CF_ACCOUNT_ID"   # 在 CF dashboard 右側欄看到
 
[site]
bucket = "./public"

抓 account_id 的方式：

CF dashboard 右上角頭像 → My Profile → 右側欄會看到 Account ID
或在 dashboard 任一頁右側欄找

如果 [site] 這個語法 wrangler 抱怨已棄用，改用 Workers Sites 或 Cloudflare Pages 流程。最新 wrangler 推薦走 Pages，跑指令：
npx wrangler pages deploy public --project-name=mental-models

步驟 9｜首次部署

cd /c/Users/alber/Desktop/AI_Playground/mental-models-quartz
 
# 1. build static site（產 public/ 目錄）
npx quartz build
 
# 2. deploy
npx wrangler pages deploy public --project-name=mental-models

第一次跑 deploy 會問：

「Create a new project?」→ Yes
Production branch name → main 或 production

成功後會輸出像這樣的 URL：

✨ Deployment complete!
   https://mental-models.pages.dev

🎉 網站已上線！

步驟 10｜（可選）綁定子網域

如果想要 https://mental-models.albertckchien.workers.dev/ 風格的 URL（跟 hbs-vault 一致）：

CF dashboard → Workers & Pages → mental-models
Custom domains 分頁
Add custom domain → 輸入 mental-models.albertckchien.workers.dev

或在 Pages 設定改 project name 也能影響預設 URL。

步驟 11｜記錄 deploy URL

部署完成後，回到 vault 更新 quartz.config.ts 的 baseUrl：

baseUrl: "mental-models.pages.dev",   // 或你的自訂網域

再跑一次 deploy 讓 SEO meta 正確。

之後的更新流程（每次想 publish 更新）

# 1. 在 mental-models-vault 內編輯（本地 Obsidian）
# 2. build vault
cd /c/Users/alber/Desktop/AI_Playground/mental-models-vault
python _scripts/prep_for_quartz.py
 
# 3. 同步到 quartz content（如果用 Option B）
cd ../mental-models-quartz
rm -rf content/*
cp -r ../mental-models-vault/_build/quartz-content/* content/
 
# 4. build + deploy
npx quartz build
npx wrangler pages deploy public --project-name=mental-models

可以包成一個 deploy.sh 腳本一鍵跑。

常見問題

Q: 部署完看到 404？ A: Check 兩件事：(1) public/ 是否有 index.html（沒有的話 quartz build 失敗了，看終端錯誤訊息）；(2) wrangler deploy 路徑指對。

Q: 中文檔名/路徑 deploy 失敗？ A: Quartz 會自動把 CJK 檔名 URL-encode，理論上 OK。如果有問題，看 public/ 內檔名是否正確產生。

Q: Dataview block 還是顯示原始 code？ A: 確認 prep_for_quartz.py 跑過了，輸出在 _build/quartz-content/。直接看 _build/quartz-content/00_入口/使用指南.md 應該已經是 markdown table 不是 dataview block。

Q: 改 vault 內容後部署沒更新？ A: 確認步驟 3 那層複製有做（從 vault _build 同步到 quartz content/）。symlink 模式下這層自動。

完成檢查清單

跑完之後對照看哪些做到：

CF Worker / Pages 專案建立
First deploy 成功，URL 能打開
首頁能看到 README
點 Latticework核心邏輯能正確跳轉
點任一條常駐工具能正確 render
使用指南內 Dataview 結果已靜態化（不是空白）
中文檔名能正確 URL access
graph view 能看到節點關係（Quartz 內建）

心智模型工具箱 · Mental Models Vault

探索

首次部署到 Cloudflare｜手把手指南