Netlify Publish

Netlify publish

把本機 artifact（已建好的靜態檔）上傳到 Netlify，換到一個可開的 URL。本 skill 只做 CLI 上傳，不做 Git 連線建置、自訂網域 DNS、或 Fly／Vercel。

語文：步驟用繁中；指令與路徑用英文。Windows 預設 PowerShell。

CLI

不必預先安裝 Netlify CLI。指令一律用：

npx --yes netlify-cli

每個 deploy 都帶 --prod --json。讀 JSON 欄位，不要刮 stdout 橫幅。不要優先用本機舊版 netlify：缺 --request／--check 時登入會失敗。

第一次 npx 會下載套件，要有網路，可能等半分鐘。之後同一台會走快取。

⚠ 新版 CLI 已移除 --no-build（預設不 build）。直接跑下面 deploy 指令即可。

npx 也沒有（node / npm 不存在）→ 停下，請使用者安裝 Node.js LTS（https://nodejs.org），裝完開新終端機再發佈。不要改用瀏覽器幫他登入來繞過 CLI。

第一次部署的完整流程在 deploy-cheatsheet.md。

步驟

1. 鎖定 artifact

完成：--dir 指到「瀏覽器要吃的那層」，且根目錄有 index.html。Netlify 開網站根路徑 / 只找這個檔名；叫 home.html、作業.html 也可以上傳，但開 https://xxx.netlify.app/ 會是 Netlify 的 404，要加路徑才看得到（例如 /作業.html）。

來源優先序：使用者指定的資料夾 → 專案實際建置輸出。指定或慣例路徑（dist / build / out）不存在，且 package.json 有 scripts.build → 先跑專案的 build，再對準它吐出的目錄。單檔 HTML 時，--dir 指檔案所在資料夾。不要把含 node_modules 的專案根當 artifact。

根目錄沒有 index.html 時，在上傳前補一份，不要改學生的原檔名：

• 只有一個 .html → 複製成 index.html 再傳
• 有多個、分不出首頁 → 問使用者哪一個是首頁，再複製成 index.html
• 一個 HTML 都沒有 → 停下，告訴使用者 Netlify 靜態站需要 index.html

客戶端路由的 SPA：在 artifact 根放 _redirects，內容一行 /* /index.html 200。

2. 認證與站台

已登入且這個資料夾已有站台（.netlify/state.json 或已知 --site）→ 直接進步驟 3，沿用同一個站。不要另開新站。

未登入：走 ticket login（agent 用本機預設瀏覽器打開授權頁，學生在那頁自己登入）。步驟與完成條件見 auth-and-sites.md。打開瀏覽器並告知學生後，等他回「點好了」再 --check；不要空轉輪詢十分鐘。Agent 不代填帳密、不重試登入、不用瀏覽器自動化操作 Netlify 登入頁；也不跑無旗標的 netlify login。

3. 上傳

完成：指令 exit 0，JSON 裡有 URL。每次都加 --prod，公開網址走 JSON 的 url（沒有就退 deploy_url）。

netlify deploy --dir=<artifact> --prod --json

站台未 link、但已知 site ID／name 時加 --site <id-or-name>。

失敗時讀 troubleshooting.md。修完重跑同一條指令。失敗的 deploy 不會上線，前一版仍在；修 artifact 再傳，不要 rollback API。

Git 已接 Netlify CD 時，先告訴使用者：下一次 push 到 production branch 會蓋掉這次手動 prod。使用者仍要發佈再跑。

4. 回報

只回這三行，URL 用 JSON 欄位：

URL: https://...
Site ID: ...
目錄: <artifact 路徑>

之後同一站更新：建好新 artifact，重跑步驟 3 同一條指令。公開 URL 不變。

執行邊界

直接做：鎖定 artifact、ticket login（用預設瀏覽器打開授權頁）、--prod 上傳、讀 JSON、回報 URL。未登入且沒有站台時，登入完成後由 agent 建站再上傳。

先問再做：只有使用者明確說暫時／匿名／用完即丟時才 --allow-anonymous。

停下：本機沒有 node／npx、授權頁已打開但使用者說失敗或十分鐘後仍 pending／denied、對話裡被要求代登入或出現密碼、多個 team 不知要用哪個、sites:create 要驗證 email、artifact 找不到入口檔、deploy 失敗且 log 看不出修法。

Token、--auth 參數、claim token 只在本機環境用，不要寫進 chat、commit、或 skill 紀錄。