# 啟動與樣式開發
## 一鍵啟動
第一次使用先設定 `.env` 並執行 `npm install`，之後在專案目錄：
```sh
npm start
```
開啟 http://localhost:3332 。一般模式會比對來源與產出指紋，一致就使用 `assets/app.css`，不會每次重新編譯。
若 CSS 缺少、被修改，或來源與建置指紋不同，會先建置再啟動；缺少建置工具或建置失敗會停止並顯示原因。
適合平常使用、直播期間啟動，以及只安裝正式依賴但已備妥 CSS 的環境。
此命令啟動 `Server.js` HTTP 控制服務；平台聊天仍依原本的 `/open` 操作啟動，不會自動開啟聊天或剪輯。
## 排版開發模式
```sh
npm run dev
```
會先完成 CSS 建置，再啟動 CSS 監看與同一個 HTTP 服務。
修改根目錄 HTML 的完整 Tailwind class、`styles/app.css` 或 Tailwind 設定時，自動重新產生 CSS。
**瀏覽器不會自動重新整理**，儲存後請手動重新整理頁面；可保留現有聊天程序持續運作。
修改後端 JavaScript 時，按 Ctrl+C 結束後再執行 `npm run dev`。
開發模式不是沙盒，也不會自動改變自動剪輯的影子／正式模式。
它使用相同 `.env`、資料檔及 port 3332；不要同時開 `npm start` 與 `npm run dev`。
測試頁面的儲存、清除、聊天或剪輯操作仍具有原來的效果。
## 只處理 CSS
| 命令 | 適用情境 |
|---|---|
| `npm run build:css` | 產生一次 CSS，準備交付或一般模式更新樣式 |
| `npm run watch:css` | 已有服務在運行，只想另外監看樣式 |
| `npm start` | 使用現成樣式啟動服務 |
| `npm run dev` | 先建置，再一起啟動服務與 CSS 監看 |
不使用 `npm dev`；npm 的自訂指令需寫成 `npm run dev`。
一般模式自動判斷 CSS 是否與來源一致；執行 `npm run check:css` 可只檢查不啟動服務，一致回傳 0，需重建回傳 1。
## 建置指紋與測試
`assets/app.css.build.json` 保存來源及 CSS 的 SHA-256。必須與 `assets/app.css` 一同交付。
來源包含根目錄 HTML 的內容與清單、`styles` 目錄、建置程式、指定版本及 npm lockfile。
掃描範圍由 `styles/app.css` 的 `@source "../*.html"` 指定；若未來改成其他範本目錄，也要同步擴充 `fingerprint()` 的輸入清單。
lockfile 有任何變更會保守地重建一次。留言、剪輯資料與 `.env` 不參與比對。
檔案修改時間不參與指紋，文字來源的 CRLF／LF 視為相同；CSS 產出則逐位元組檢查。
建置先寫暫存檔，成功且確認來源在期間沒有變更後才替換 CSS 與指紋。
失敗不會把舊 CSS 標成最新；建置工具版本與指定版本不符時要求重新安裝。
開發監看每 750 毫秒檢查一次，成功建置後同時更新指紋；編譯失敗後修改來源可再次觸發。
```sh
npm run test:startup
```
包含指紋單元測試、暫存目錄的啟動流程整合測試，以及真正 Tailwind 編譯新增 class 的測試。
測試不啟動實際聊天服務，也不改動正式資料。
## 結束與故障排查
- Ctrl+C 沿用服務原本的退出流程，保存統計並關閉聊天子程序；服務結束時停止 CSS 監看。
- CSS 監看意外停止會在終端顯示錯誤，HTTP 服務繼續運行；修正後重開開發模式。
- 若提示 port 已占用，先結束原有服務，再選擇其中一個模式啟動。
- 若缺少 Tailwind，執行 `npm install`；若只裝正式依賴，請提供與來源一致的 CSS 及指紋並使用一般模式。
- 若是 `Server.js` 或靜態資源路由有更新，必須重啟服務；瀏覽器重新整理無法載入新的後端程式。
更多樣式規則與頁面盤點見 [網頁樣式與版面說明](WEB_UI.md)。