4.8 使用指南
部署
把 notecraftapp build 的產物複製出來，放到 GitHub Pages、Netlify 或任何靜態主機；也說明筆記圖片怎麼進產物、子路徑怎麼設，以及部署出去的站少了哪些功能。
notecraftapp build 產生的是純靜態網站：HTML、CSS、JS 與一份 /wb-index.json，沒有任何執行期 API。能放靜態檔案的主機都能用。
產生產物
npx notecraftapp build ./notes產物在 ~/.notecraft/cache/<hash>/dist/。<hash> 是筆記資料夾絕對路徑的 SHA-1 前 12 碼，build 結束時最後一行會印出完整路徑：
[notecraftapp] dist: : /Users/you/.notecraft/cache/2bb4fbdcdaa2/dist部署前先把它複製出來，不要直接拿快取目錄去部署。下一次 build 或 serve 的背景 rebuild 會整個換掉這個資料夾。
mkdir -p site-out
cp -R ~/.notecraft/cache/<hash>/dist/. site-out/升級 notecraftapp 或改了下面提到的 NOTECRAFT_BASE 之後，下一次 build 會自動重建，不必加 --rebuild（1.8.1 起；更早的版本要加）。快取規則見運作原理。
npx notecraftapp build ./notes 站不在網域根目錄時，先設 NOTECRAFT_BASE ~/.notecraft/cache/<hash>/dist/ build 最後一行印出完整路徑；筆記引用的圖片已複製進 notes-assets/ cp -R <dist>/. site-out/ build 或 serve 的背景 rebuild 會整個換掉它 site-out/ GitHub Pages、Netlify 或任何靜態主機 pagefind/ 跟著產物走） 筆記裡的圖片
筆記用相對路徑引用的圖片，會被改寫成 /notes-assets/<相對於筆記資料夾的路徑>（見圖片與附件）。build 結束時會把產物實際引用到的檔案照同樣的相對路徑複製進 dist/notes-assets/，不必另外處理，直接部署就看得到。
以一篇引用 ./cover.png 與 sub/inner.png 的 hello.md 為例：
dist/notes/hello/index.html 的 src 設 NOTECRAFT_BASE=/my-notes 時  /notes-assets/cover.png /my-notes/notes-assets/cover.png  /notes-assets/sub/inner.png /my-notes/notes-assets/sub/inner.png  ../outside.png落在筆記資料夾外，照原樣保留 不會進產物 dist/notes-assets/cover.png 與 dist/notes-assets/sub/inner.png；筆記資料夾裡沒被引用的圖片不會進產物。幾個規則：
- 只複製 HTML 裡真的出現的
/notes-assets/…網址，筆記資料夾裡沒被引用的圖片不會進產物。手寫成/notes-assets/開頭的 PDF 連結也算引用 - 只複製支援的格式；
.md、.mdx、.notecraft/不會被帶出去 - 解析後落在筆記資料夾外面的路徑（含指向外面的 symlink）不複製
- 引用的檔案不存在、或被上面兩條擋下時，build 照樣完成，log 會印一行
[WARN] [notecraft-notes-assets]列出是哪個路徑
只改了圖片、沒動筆記時，build 也會發現上次複製過的圖片變了而重建，不需要 --rebuild。
部署到子路徑
站不在網域根目錄時（例如 GitHub Pages 的專案站 https://<帳號>.github.io/<repo>/），build 時設環境變數 NOTECRAFT_BASE：
NOTECRAFT_BASE=/my-notes npx notecraftapp build ./notes- 站內連結、CSS／JS 路徑、改寫後的圖片網址都會加上前綴，例如
/my-notes/notes-assets/cover.png - 產物的目錄結構不變，
index.html仍在dist/最上層。把整份內容放到主機上/my-notes/對應的位置 - 圖片仍放在
dist/notes-assets/，跟著整份產物一起放上去就對得到/my-notes/notes-assets/…
放上靜態主機
產物的每一頁都是 <路徑>/index.html，連結寫成 /notes 這種不帶結尾斜線的形式，主機要能把它對到 notes/index.html。GitHub Pages 與 Netlify 預設都會這樣處理。
| 主機 | 做法 |
|---|---|
| GitHub Pages | 用 GitHub Actions 部署：build、複製產物，交給 actions/upload-pages-artifact。若改用「從分支部署」，產物裡有 _astro/ 資料夾，要在根目錄放一個空的 .nojekyll |
| Netlify | 把 site-out/ 整個資料夾拖到 Netlify 的手動部署頁；在 Netlify 上 build 時，build 指令要包含複製產物，publish 目錄指向複製出來的資料夾 |
| 其他靜態主機 | 上傳 site-out/ 的內容 |
在 CI 裡不知道 <hash>，從 build 最後印的那一行取路徑：
DIST=$(npx notecraftapp build ./notes --rebuild | sed -n 's/^\[notecraftapp\] dist: *: //p')
mkdir -p site-out
cp -R "$DIST"/. site-out/CI 需要 Node 22（見系統需求）。第一次執行 npx notecraftapp 會先安裝一次，約 30 秒。
部署後少了什麼
部署出去的站就是 build 的產物，和 serve 看到的一樣是唯讀的：
| 項目 | 在部署的站上 |
|---|---|
「+ 新增筆記」、標籤編輯、/tags 的重新命名與刪除 | 不輸出 |
| 筆記頁首「⋯」選單（以 VS Code 編輯、重新生成提示、刪除筆記） | 不輸出，產物裡也不含本機絕對路徑 |
| Drawer 的「複製生成提示」、沒有簡報時的「生成簡報」 | 不輸出 |
/plugins 的啟用／停用開關 | 只顯示狀態 |
| 閱讀進度、頁籤、收藏 | 存在每位訪客自己的瀏覽器（localStorage），不會互通 |
產物裡不會有你電腦上的路徑。build 結束前會檢查所有 .html、.json，若含專案、筆記資料夾或 app 的絕對路徑，build 直接失敗並列出是哪些檔案（1.8.5 起）。遇到這個錯誤請回報 issue，附上終端機列出的片段。
寫入功能都要在本機用 view，見在介面新增與編輯。
全文搜尋
build 完會在產物裡建好 pagefind 索引（pagefind/ 資料夾），整個資料夾一起上傳，部署的站上 ⌘K 就能搜內文，不用另外跑 pagefind。若終端機印了建索引失敗的警告，站仍可部署，只是沒有「內文」分區。
搜尋範圍與限制見指令面板與全文搜尋。