執行 是做什麼的?
一個網站只有在被實際運行看到後才算完成。原始碼告訴你別人想表達什麼;瀏覽器則告訴你使用者實際得到什麼。此技能是從資料夾到渲染頁面的最短途徑。
執行方式
node <skill 資料夾>/scripts/serve.mjs <目錄> [--port 4173] [--open] [--shot 輸出.png] [--stop] [--detect]
--detect僅列印偵測到的資訊而不啟動任何服務。當目錄不熟悉時,請先執行此選項。--port從指定連接埠開始尋找,並使用下一個空閒連接埠,因此可以同時執行兩個專案。--open開啟預設瀏覽器。--shot 輸出.png透過 Playwright 以 1440 寬度、全頁高度渲染頁面。--stop從.run/state.json終止進程樹。
它會在專案旁邊寫入 .run/state.json(包含 pid、port、url、command)和 .run/server.log。這兩個檔案是啟動與停止之間完整的交接檔案。
偵測項目
| 找到的內容 | 執行方式 |
|---|---|
包含 dev、start、serve 或 preview 腳本的 package.json | 在空閒連接埠上執行 npm run <該腳本>,並設定 PORT 環境變數 |
根目錄下的 index.html | 對該資料夾執行 python -m http.server |
public/index.html、dist/index.html、build/index.html | 以建置輸出目錄為根的靜態伺服器 |
| 有設定檔但無腳本 | 報告並停止:該專案需要自己的命令 |
go.mod、Cargo.toml、pubspec.yaml | 報告並停止:請使用專案自身的執行命令 |
框架特定細節、預設連接埠以及值得了解的失敗模式:請參閱 references/stacks.md。
解讀結果
該腳本僅證明三件事:進程已啟動、連接埠有回應、頁面已渲染。它無法告訴你的是:
- 佈局在 375、768 和 1440 寬度下是否正確(請使用
sitecraft/scripts/verify.mjs進行驗證) - 主控台是否乾淨(此處未擷取;
verify.mjs會擷取) - 截圖的頁面是否為使用者想要的頁面(請檢查 URL 是否與你要求的路由相符)
因此循環是:serve.mjs --shot,用你自己的眼睛查看圖片,修正,再次截圖。單次通過最多渲染三次;超過這個次數,問題在於計劃,而非 CSS。
規則
- 絕不讓伺服器持續運行。 檢查完成後請停止它,或者明確說明它仍在運行以及在哪個連接埠上。使用者機器上殘留的開發伺服器會造成他們需要清理的混亂。
- 不要啟動你無法停止的東西。 如果專案需要 Docker、資料庫或付費 API 金鑰,請在啟動任何東西之前說明。
- 回報真實的 URL。 使用
localhost:4173,而不是「應用程式」。如果因為 4173 被佔用而導致連接埠變更,請說明新的連接埠。 - 在猜測前先讀取日誌。 啟動失敗幾乎總是因為缺少依賴項、缺少環境變數或連接埠已被佔用。
.run/server.log中有答案,引用實際錯誤勝過理論推測。 - 未經說明不要安裝。 如果缺少
node_modules,npm install通常是正確的,但這也是對他們專案的修改。請先執行,然後說明已執行,或者當安裝內容較大時徵詢一次同意。 - 靜態優先於框架。 當建置輸出存在且為最新時,提供
dist/目錄比開發伺服器更快且更真實。
無法啟動時的處理
- 讀取
.run/server.log並引用第一個真正的錯誤,而不是最後一行。 - 缺少依賴項:在專案中執行
npm install,然後重試。 - 缺少環境變數:尋找
.env.example,說明需要哪些變數,且如果某個值是秘密且不存在則停止。 - 連接埠已被佔用:腳本會自動移至下一個空閒連接埠;若仍失敗,通常原因是框架設定中寫死了連接埠。
- 需要建置步驟:先執行
npm run build,然後提供dist/目錄。 - 原生或容器化:請參考專案的說明文件來執行命令。並非所有技術棧都能用腳本處理。
檢查清單
- 偵測了技術棧而非假設一個
- 啟動了服務並看到了真實的 HTTP 回應,而不僅是產生了進程
- 回報了確切的 URL 和連接埠
- 查看了截圖,而不僅是日誌
- 確認路由與預期的頁面相符
- 停止了服務,或說明它仍在運行及其位置
- 在失敗時引用了真正的錯誤