4.7 使用指南
即時預覽
serve 會監看筆記與 .notecraft 的變動、在背景重新 build，完成後讓瀏覽器自動重新載入；適合一邊讓 Claude Code 寫檔、一邊看結果。
notecraftapp serve 預設帶背景 rebuild 與自動重新載入。檔案一改，伺服器重新 build 一份靜態站，成功後通知已開啟的頁面重新整理。你不用重啟伺服器，也不用手動按重新整理。
npx notecraftapp serve ./notes監看哪些檔案
| 位置 | 檔案 |
|---|---|
| 筆記資料夾 | .md、.mdx，以及資料檔 .json（. 開頭的資料夾不看） |
.notecraft/ | 第一層的 .json，例如 series.json、plugins.json、ignore.json |
.notecraft/components/ | AI 生成的 .tsx 元件 |
.notecraft/plugins/ | 已安裝 plugin 的 .tsx、.ts、.json |
.notecraft/ 指的是你執行指令那個目錄底下的 .notecraft/。
被 ignore.json 排除的檔案改了不會觸發 rebuild，被排除的資料夾也不監看。改 ignore.json 本身會換用新規則並 rebuild 一次；啟動 serve 時被排除、之後才取消排除的資料夾，要重開 serve 才會開始監看。view 則是在 ignore.json 存檔時自動重新啟動 dev server。
一次 rebuild 怎麼跑
- 偵測到變動後等 300ms，這段時間內的連續存檔合併成一次
- 執行
astro build，輸出到快取裡的dist.next/，再對它建 pagefind 全文索引（索引失敗只印警告，不算 build 失敗） - 成功後把
dist.next/換成dist/，舊的那份在背景刪掉 - 透過 SSE（
/__notecraft/events）通知所有開著的頁面，頁面自動重新載入
rebuild 進行中又有檔案變動，會在這一輪結束後再跑一輪，不會漏掉。終端機會印出觸發的檔案與這輪花了多久。
build 失敗時
- 已有能用的 dist：舊的
dist/保留、繼續服務，瀏覽器不重新載入，只在 console 印警告。錯誤細節在終端機 - 第一次 build 就失敗：伺服器照樣啟動，所有頁面顯示一張等待頁，上面有錯誤節錄。修好檔案、rebuild 成功後，這頁會自動換成真正的內容
所以 build 失敗時不用重啟 serve，修好檔案存檔就好。
搭配 Claude Code
開兩個終端機，都在專案根目錄：
# 終端機 1：開 viewer
npx notecraftapp serve ./notes# 終端機 2：開 Claude Code，請它處理筆記裡的 @ai-visualize 標記
claudeClaude Code 把元件寫進 .notecraft/components/、把 import 寫回筆記，serve 偵測到就 rebuild，瀏覽器自動顯示新的圖。兩邊只透過檔案系統溝通，不需要互相設定。
關掉自動重新載入
npx notecraftapp serve ./notes --no-watch帶 --no-watch 時不監看檔案、不注入重新載入的 script，serve 只服務現有的 build 產物。啟動時仍會照快取規則判斷要不要先 build 一次。
notecraftapp build 的產物本身不含任何重新載入的 script；這段 script 是 serve 在回應 HTML 時才加進去的。