發布靜態網站
目標
發布或準備部署一個完整的靜態網站。
此技能適用於可部署的 HTML/CSS/JS 輸出,例如 site/、dist/、out/、public/ 或 docs/。它也可以在建置框架專案產生靜態輸出資料夾後發布該專案,但不應為了部署而將純靜態網站轉換為框架專案。
預設立場:
- 偏好簡單的靜態託管,而非特定框架的部署。
- 對於使用者會持續編輯的網站,偏好基於 Git 的部署。
- 僅對快速的一次性發布偏好直接上傳。
- 除非使用者明確要求,否則不建立遠端儲存庫、不推送程式碼、不變更 DNS、不新增網域,也不部署到付費帳戶。
合約
輸入:
- 靜態部署根目錄,例如
site/、dist/、out/、public/、docs/或儲存庫根目錄。 - 偏好的平台或目標:GitHub Pages、Cloudflare Pages、Netlify、Vercel、自訂網域、僅提供指導或即時部署。
- 目前的 Git/儲存庫狀態、平台帳戶存取權、CLI/瀏覽器登入狀態以及任何部署限制。
輸出:
- 具體的部署設定:平台、分支、建置指令、基礎目錄、發布/輸出目錄以及必要的設定檔。
- 可選的特定平台設定,例如 GitHub Pages 工作流程、
netlify.toml、vercel.json、.nojekyll或CNAME。 - 實際執行部署時提供即時 URL 和部署後驗證。
- 當無法取得憑證或帳戶存取權時,提供手動儀表板操作步驟。
邊界:
- 不建置或重新設計網站;將缺陷導向適當的子技能。
- 除非獲得明確授權,否則不推送、不建立儲存庫/專案、不上傳、不綁定網域、不變更 DNS 或不使用付費資源。
- 除非使用者明確接受僅限伺服器根目錄的行為,否則不將部署用作解決本機/靜態路徑相容性問題的變通方法。
成功閘道:
review-static-site已通過,或未解決的風險已明確列出。- 部署根目錄包含
index.html,且平台將發布正確的資料夾。 - 部署後,線上 URL 能載入首頁、資產、導航功能及代表性的子頁面。
若閘道失敗:
- 在部署前修復路徑、資產、編碼或頁面類型的阻礙。
- 將內容/設計/匯入問題導向
personalize-site、edit-site-part、add-blog-posts、make-personal-site或copy-website-style。 - 重新執行
review-static-site,然後重試或更新部署設定。
參考資料
僅載入所選平台或問題所需的參考資料:
- 路徑策略與直接開啟相容性:
references/path-strategy.md。 - Cloudflare Pages Git 整合與直接上傳:
references/cloudflare-pages.md。 - GitHub Pages 分支來源與 Actions 工作流程:
references/github-pages.md。 - Netlify 儀表板與
netlify.toml:references/netlify.md。 - Vercel 儀表板與
vercel.json:references/vercel.md。
官方文件:
- GitHub Pages 發布來源:https://docs.github.com/en/pages/getting-started-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site
- GitHub Pages 自訂工作流程:https://docs.github.com/en/pages/getting-started-with-github-pages/using-custom-workflows-with-github-pages
- Cloudflare Pages 靜態 HTML:https://developers.cloudflare.com/pages/framework-guides/deploy-anything/
- Cloudflare Pages Git 整合:https://developers.cloudflare.com/pages/get-started/git-integration/
- Cloudflare Pages 直接上傳:https://developers.cloudflare.com/pages/get-started/direct-upload/
- Netlify 建立部署:https://docs.netlify.com/deploy/create-deploys/
- Netlify 建置設定:https://docs.netlify.com/build/configure-builds/overview/
- Vercel 部署:https://vercel.com/docs/deployments
- Vercel 專案設定:https://vercel.com/docs/project-configuration
部署模式
首先確定使用者實際想要什麼:
- 僅提供指導:解釋平台選擇和確切設定。除非有用,否則不編輯檔案。
- 準備儲存庫:新增所需的設定檔,並告知使用者在託管儀表板中點擊哪些按鈕。
- 立即部署:僅在使用者明確要求且存在必要的 CLI/驗證/工作階段時才執行遠端操作。
- 驗證即時 URL:在瀏覽器中開啟已部署的 URL,並與本機網站進行比對。
如果缺少憑證、帳戶存取權、瀏覽器登入或 CLI 驗證,請提供確切的儀表板步驟,而不是發明變通方法。
工作流程
- 識別靜態輸出資料夾以及使用者的偏好平台(如果有的話)。
- 在發布前呼叫或建議使用
review-static-site。 - 確認部署根目錄包含
index.html。 - 在發布前檢查資產路徑,並轉換意外的根目錄絕對路徑(站點本機路徑)。當路徑行為不明確時,載入
references/path-strategy.md。 - 選擇最簡單的相符平台和部署模式。
- 載入所選平台的參考資料,並僅新增該平台所需的設定檔。
- 如果透過 Git 部署,請檢查 Git 狀態,避免包含不相關或私密檔案。
- 如果使用者授權了遠端操作,則推送或部署雙方同意的內容。
- 發布後,開啟即時 URL 並在瀏覽器中驗證已部署的網站。
預檢檢查清單
在撰寫部署設定或告知使用者設定之前,請執行這些檢查:
- 部署根目錄:選擇直接包含
index.html的資料夾。 - 進入頁面:
index.html必須存在於部署根目錄的頂層。 - 直接開啟預覽:根目錄的
index.html在直接從檔案系統開啟時,應能保持 CSS、JS、圖片和導航功能正常,除非使用者明確接受僅限伺服器行為。 - 本機 HTTP:使用
python -m http.server提供部署根目錄的服務,並確認能透過http://127.0.0.1:<port>/正常運作。 - 靜態審查:執行或建議執行
review-static-site,檢查連結、UTF-8 可讀性、預留位置殘留、瀏覽器渲染、隱私殘留和行動版版面。 - 資產路徑:檢查
href、src、srcset、CSSurl(...)、字型、favicon、封面圖片、RSS、sitemap 和 manifest 連結。 - 私密資料:確保不會發布權杖、本機檔案系統路徑、草稿筆記、原始網站身分和個人機密。
- 輸出完整性:確認子頁面、文章、圖片、供應商字型、KaTeX/數學資產和複製的媒體都存在於部署根目錄內。
將以下情況視為阻礙:
- 部署根目錄中沒有
index.html。 - 本機 CSS、JS、圖片、字型、RSS、sitemap 或供應商資產路徑損壞。
- 來源檔案包含 mojibake 或無法讀取的編碼。
- 產生的個人網站仍包含應已被取代的複製來源身分。
- 在產生的純靜態網站中,仍存在意外的根目錄絕對路徑(網站本機路徑),例如
/assets/...、/posts/...、/data/...或/images/...。 - 網站僅能透過本機 HTTP 正常運作,因為根目錄絕對路徑是從
127.0.0.1提供服務,但直接開啟檔案或子路徑部署會導致 CSS/JS/圖片遺失。 - 會部署到涉及隱私的檔案或機密。
- 平台會部署到錯誤的資料夾。
平台選擇
對於純靜態個人網站,使用此預設排名:
- Cloudflare Pages Git 整合:對於產生的
site/資料夾和未來更新,最佳預設選項。 - 搭配 GitHub Actions 的 GitHub Pages:當使用者希望一切都在 GitHub 內時的最佳選擇。
- Netlify:簡單的靜態託管,具有友善的預覽和儀表板設定。
- Vercel:當使用者已在使用 Vercel 或未來可能轉向 Next.js 時的好選擇,但不是純 HTML 的預設選項。
決策規則:
- 如果使用者希望摩擦力最小且擁有 GitHub 儲存庫:Cloudflare Pages Git 整合。載入
references/cloudflare-pages.md。 - 如果使用者希望僅限 GitHub 的託管:GitHub Pages。載入
references/github-pages.md。 - 如果部署檔案位於儲存庫根目錄或
/docs:GitHub Pages 分支來源是可接受的。 - 如果部署檔案位於
site/、dist/、out/或其他自訂資料夾:偏好將 GitHub Actions 用於 GitHub Pages。 - 如果使用者今天想要手動上傳:Cloudflare Direct Upload 或 Netlify 手動部署。
- 如果使用者已有 Vercel 帳戶/專案:使用 Vercel 並明確指定輸出目錄設定。
框架靜態輸出
如果網站不是純 HTML/CSS/JS:
- 檢查
package.json、框架設定和現有腳本。 - 使用專案現有的建置指令;不要發明 npm 工作流程。
- 發布最終的靜態輸出資料夾,而不是來源資料夾。
- 常見的輸出包括
dist、out、build、.output/public和public,具體取決於框架。 - 對於 Next.js 靜態匯出,請在將
out/視為最終輸出之前,確認專案確實已設定為靜態匯出。 - 對於 Vue/Vite/Astro 風格的專案,請在建置成功後發布設定的輸出目錄。
如果使用者要求的是純靜態發布且不存在框架檔案,請不要引入 npm。
設定檔政策
僅新增與所選平台相符的設定檔:
- GitHub Pages Actions:
.github/workflows/pages.yml。 - GitHub Pages 自訂網域:
CNAME位於部署根目錄,僅在使用者提供網域時新增。 - GitHub Pages Jekyll 繞過:
.nojekyll位於部署根目錄,在有用時新增。 - Netlify:僅在儀表板設定不足或使用者希望將設定放在 Git 中時才新增
netlify.toml。 - Vercel:僅在 Vercel 需要明確的輸出設定時才新增
vercel.json。 - Cloudflare Pages:對於純靜態網站,儀表板設定通常就足夠了。
不要一次為所有平台新增部署設定。
Git 與遠端安全性
在執行任何遠端操作之前,請說明將要進行的操作,並確認使用者已要求:
- 建立 GitHub 儲存庫。
- 新增遠端。
- 暫存或提交檔案。
- 將提交推送到遠端分支。
- 啟用 GitHub Pages。
- 建立 Cloudflare、Netlify 或 Vercel 專案。
- 將檔案上傳到託管提供者。
- 新增環境變數。
- 新增自訂網域或變更 DNS 記錄。
在暫存或推送前:
- 執行
git status --short。 - 區分產生的網站檔案與不相關的使用者變更。
- 不要暫存不相關的變更。
- 不要發布私密筆記、憑證、本機路徑、含有機密的螢幕截圖或暫存檔案。
切勿將機密、權杖、私密筆記或本機檔案系統路徑放入靜態網站或部署設定中。
部署後驗證
在平台回報即時 URL 後:
- 使用實際可用的互動式瀏覽器工具開啟已部署的 URL。「可用」表示它暴露在當前回合的可呼叫工具清單中。在 Codex 中,這可能是 Browser/應用內瀏覽器外掛程式(當路由到回合中時)。
- 確認首頁不是 404、空白頁或目錄列表。
- 確認 CSS、JavaScript、圖片、字型、favicon、RSS、sitemap 和供應商資產能從部署的網域載入。
- 點擊主要導航以及每種頁面類型的至少一個代表性子頁面。
- 測試桌面和行動裝置寬度。
- 檢查瀏覽器主控台是否有遺失的資產或 JavaScript 錯誤。
- 確認後設資料、標題、描述、Open Graph 圖片、標準 URL、RSS、sitemap 和 robots 檔案(如果存在)。
- 如果使用 GitHub 專案 Pages,請特別檢查儲存庫子路徑下的子頁面和資產 URL。
- 如果使用自訂網域,請在設定後驗證 HTTPS 以及頂級網域和
www之間的重新導向。
如果沒有可呼叫的互動式瀏覽器工具,請不要假裝發生了即時瀏覽器驗證。如果即時視覺驗證很重要,請要求使用者啟用或呼叫瀏覽器工具;對於 Codex,這可能意味著發送一個明確提及 @browser 的請求。如果使用者未重新路由或用戶端沒有此類工具,則回退到 Playwright、螢幕截圖、HTTP 檢查或靜態檢查,並說明限制。
當互動式瀏覽器工具實際可呼叫時,不要預設使用 Playwright 或僅使用螢幕截圖進行即時驗證。僅將 Playwright 用作備援方案,或當使用者明確要求腳本化部署檢查時使用。
如果已部署的網站與本機預覽不同,請先檢查部署日誌、輸出目錄和資產路徑策略,然後再變更設計程式碼。
輸出
保持最終面向使用者的報告簡潔:
- 選擇的平台及其原因。
- 已發布或準備的靜態資料夾。
- 部署模式:指導、已準備設定、Git 整合、直接上傳或即時部署。
- 使用的設定:分支、建置指令、基礎目錄、發布/輸出目錄。
- 已變更的設定檔(如果有的話)。
- 所選平台的官方指南 URL。
- 即時 URL(如果已部署)。
- 已執行的驗證以及任何剩餘的手動步驟。
如果只要求提供指導,請不要假裝網站已部署。提供具體的平台設定和官方指南連結。