netlify-deploy

Netlify 部署 Skill

使用 Netlify CLI 將 Web 專案部署至 Netlify，支援智慧偵測專案設定與部署情境。

概觀

此 Skill 透過以下方式實現 Netlify 自動化部署：

• 驗證 Netlify CLI 身分驗證狀態
• 偵測專案設定與前端框架
• 連結至現有網站或建立新網站
• 部署至預覽或正式環境

先決條件

• Netlify CLI：透過 npx 執行（無需全域安裝）
• 身分驗證：具備已登入會話的 Netlify 帳號
• 專案：目前目錄中需包含有效的 Web 專案
• 當沙盒限制阻擋部署網路連線時，請使用 sandbox_permissions=require_escalated 重新執行。
• 部署可能需要幾分鐘時間，請設定適當的逾時值。

身分驗證模式

此 Skill 採用預先驗證 Netlify CLI的方式：

1. 使用 npx netlify status 檢查身分驗證狀態
2. 若未驗證，引導使用者執行 npx netlify login
3. 若無法建立身分驗證，則平滑降級並提示失敗原因

身分驗證可使用以下任一方式：

• 瀏覽器 OAuth 驗證（主要方式）：netlify login 會開啟瀏覽器進行驗證
• API 金鑰（替代方式）：設定 NETLIFY_AUTH_TOKEN 環境變數

工作流程

1. 驗證 Netlify CLI 身分驗證狀態

檢查使用者是否已登入 Netlify：

npx netlify status

預期輸出模式：

• ✅ 已驗證：顯示已登入使用者的 Email 與網站連結狀態
• ❌ 未驗證：顯示 "Not logged into any site" 或身分驗證錯誤

若未驗證，引導使用者執行：

npx netlify login

這會開啟瀏覽器視窗進行 OAuth 身分驗證。等待使用者完成登入後，再次執行 netlify status 進行確認。

替代方案：API 金鑰驗證

若無法使用瀏覽器驗證，使用者可以設定：

export NETLIFY_AUTH_TOKEN=your_token_here

Token 可於此處建立：https://app.netlify.com/user/applications#personal-access-tokens

2. 偵測網站連結狀態

根據 netlify status 的輸出結果判定：

• 已連結：網站已連接至 Netlify（顯示網站名稱/URL）
• 未連結：需要連結或建立新網站

3. 連結至現有網站或建立新網站

若已連結 → 跳至步驟 4

若未連結，嘗試透過 Git Remote 進行連結：

# 檢查專案是否基於 Git
git remote show origin

# 若為 Git 專案，提取遠端 URL
# 格式：https://github.com/username/repo 或 git@github.com:username/repo.git

# 嘗試透過 Git 遠端網址進行連結
npx netlify link --git-remote-url <REMOTE_URL>

若連結失敗（網站尚未存在於 Netlify）：

# 互動式建立新網站
npx netlify init

這會引導使用者完成：

1. 選擇團隊/帳號
2. 設定網站名稱
3. 設定建置組態
4. 視需要建立 netlify.toml

4. 驗證套件相依性

在部署之前，請確保已安裝專案相依套件：

# 針對 npm 專案
npm install

# 針對其他套件管理工具，請偵測並使用相應的指令
# yarn install、pnpm install 等

5. 部署至 Netlify

根據情境選擇部署類型：

預覽/草稿部署（現有網站的預設選項）：

npx netlify deploy

這會建立一個帶有專屬 URL 的部署預覽頁面，方便進行測試。

正式環境部署（適用於新網站或明確要求的正式部署）：

npx netlify deploy --prod

這會直接部署至正式上線的 URL。

部署流程：

1. CLI 偵測建置設定（從 netlify.toml 讀取或提示使用者輸入）
2. 在本機建置專案
3. 上傳建置完成的資產至 Netlify
4. 回傳部署完成的 URL

6. 回報結果

部署完成後，向使用者回報：

• 部署 URL：本次部署的專屬 URL
• 網站 URL：正式環境 URL（若為正式部署）
• 部署日誌：查看 Netlify Dashboard 日誌的連結
• 後續步驟：建議使用 netlify open 查看網站或 Dashboard

處理 netlify.toml

若存在 netlify.toml 檔案，CLI 會自動使用它。若不存在，CLI 會提示輸入以下設定：

• 建置指令：例如 npm run build、next build
• 發布目錄：例如 dist、build、.next

常見框架預設值：

• Next.js：建置指令 npm run build，發布目錄 .next
• React (Vite)：建置指令 npm run build，發布目錄 dist
• 靜態 HTML：無建置指令，發布目錄為目前目錄

Skill 應盡可能從 package.json 偵測框架並建議合適的設定。

完整工作流程範例

# 1. 檢查身分驗證
npx netlify status

# 若未驗證：
npx netlify login

# 2. 連結網站（視需要）
# 先嘗試基於 Git 的連結
git remote show origin
npx netlify link --git-remote-url https://github.com/user/repo

# 若網站不存在，建立新網站：
npx netlify init

# 3. 安裝相依套件
npm install

# 4. 部署（預覽測試）
npx netlify deploy

# 5. 部署至正式環境（準備就緒時）
npx netlify deploy --prod

錯誤處理

常見問題與解決方案：

"Not logged in"（未登入）
→ 執行 npx netlify login

"No site linked"（未連結網站）
→ 執行 npx netlify link 或 npx netlify init

"Build failed"（建置失敗）
→ 檢查 netlify.toml 或 CLI 提示中的建置指令與發布目錄
→ 確認已安裝所有相依套件
→ 檢查建置日誌以獲取具體錯誤訊息

"Publish directory not found"（找不到發布目錄）
→ 確認建置指令已順利完成
→ 檢查發布目錄路徑是否正確

疑難排解

進階網路存取權限 (Escalated Network Access)

若部署因網路問題（如連線逾時、DNS 錯誤、連線重置）而失敗，請使用提權（sandbox_permissions=require_escalated）重新執行部署。當沙盒網路限制阻擋外網請求時，部署需要進階網路權限。

向使用者提示的範例說明：

部署至 Netlify 需要進階網路存取權限。我可以透過提權重新執行指令，請問是否要繼續？

環境變數

關於機密資訊與組態設定：

1. 切勿將機密資訊（Secrets）提交至 Git
2. 在 Netlify Dashboard 中設定：Site Settings → Environment Variables
3. 在建置流程中透過 process.env.VARIABLE_NAME 存取

小撇步

• 先使用 netlify deploy（不加 --prod）進行測試，再部署至正式環境
• 執行 netlify open 可在 Netlify Dashboard 中檢視網站
• 執行 netlify logs 可檢視函式日誌（若使用 Netlify Functions）
• 使用 netlify dev 可在本地搭配 Netlify Functions 進行開發

參考資料

• Netlify CLI Docs: https://docs.netlify.com/cli/get-started/
• netlify.toml Reference: https://docs.netlify.com/configure-builds/file-based-configuration/

隨附參考文件（依需求載入）

• CLI commands
• Deployment patterns
• netlify.toml guide