Opencode Netlify

部署網頁與隱藏金鑰（Netlify）

官方文件查證日期：2026-07-27 依據：https://docs.netlify.com/manage/accounts-and-billing/billing/billing-for-credit-based-plans/credit-based-pricing-plans/、https://docs.netlify.com/manage/accounts-and-billing/billing/billing-for-credit-based-plans/how-credits-work/、https://docs.netlify.com/build/functions/get-started/、https://docs.netlify.com/build/environment-variables/overview/、https://docs.netlify.com/api-and-cli-guides/cli-guides/get-started-with-cli/、https://docs.netlify.com/api/get-started/、https://docs.netlify.com/build/build-with-ai/netlify-mcp-server/、https://vercel.com/docs/limits/fair-use-guidelines、https://vercel.com/docs/cli/deploy

⚠️ 額度與計價數字是查證當天的狀態，服務商隨時會調整，以官方頁面為準。

🔴 第一件事：點數紀律（不看這段，後面全白做）

Netlify 從 2025-09-04 起改成點數制。這天之後註冊的新帳號，一律進入這個方案（研習現場當場註冊的老師，100% 都是）。

🔴 而這些完全不用點數（0 點）

🔴 所以本包只有一條核心紀律

先草稿，確認沒問題，才正式發布。

你可以無限次草稿部署，看到一模一樣的畫面、按到一模一樣的按鈕， 一點都不扣。

每一次「先 --prod 上去看看再說」，都是把 20 分之 1 的月配額丟掉。 一個下午改五次版面 ＝ 75 點 ＝ 當月四分之一沒了。

研習現場請直接這樣講：

• netlify deploy ＝ 試印。免費、無限次、印壞了不心疼。
• netlify deploy --prod ＝ 送印。一個月只有 20 張紙。

⚠️ 「20 次」是理論值，實際請抓 15～18 次

三個原因：

1. 點數還沒歸零，正式部署就可能先被擋。 使用者社群有多筆回報：帳面還剩 26～30 點，正式部署已經被拒絕。官方沒有說明保留門檻是多少，所以不要規劃用到見底。
2. 點數不是只有部署在吃（見下方「還有什麼會吃點數」）。
3. 撞到 API 速率限制而失敗的部署雖然 0 點，但你會忍不住重試，重試成功那次就扣了。

🔴 給 AI Agent 的硬規則： 除非使用者這一輪明確說「正式發布」「上線」「要印 QR Code 了」，否則一律只做草稿部署。 不准為了「順便驗證一下」自己加 --prod。每一次 --prod 都要先問過使用者。

還有什麼會吃點數

除了正式部署，這些也從同一個 300 點扣：

🔴 影片、大圖不要放進 Netlify 站台。 放 YouTube、放 Google 雲端硬碟，網頁只放連結。 這是本包最容易被忽略、但最會偷偷把點數吃光的一條。

📌 AI Gateway 建議不要當主線。 它是 Netlify 幫你代打 AI API 的服務，好處是不用自己申請金鑰， 壞處是用掉的每一分錢都在扣你的部署配額。本包步驟三教的是「自己的金鑰 ＋ 自己的函式」， 這條路的 AI 費用算在 AI 服務商那邊，不會咬掉你這個月能不能發布網頁。

這一包在研習裡的位置（兩個用途）

這一包會在研習裡出現兩次，因為它同時是兩種東西：

用途 A（第二天上午）：「連接外部工具」的第三條通道

前兩條你已經走過了：

前兩條是「把外面的東西拿進來」，這一條是把你的東西送出去。 做完之後，你桌上那個 index.html 變成一個全世界都打得開的網址，可以印成 QR Code 貼在教室後面。

用途 B（第三天下午）：作品⑥ 的後端

到了第三天，你手上會有一把 API 金鑰（AI、字幕、翻譯……）。 金鑰不能寫在網頁裡 —— 寫進去等於公告周知，任何人按 F12 就抄走，然後用你的額度。

Netlify Functions 就是解法：把金鑰放在你自己的伺服器上，前端只呼叫自己的後端。

❌ 壞的做法
   學生的瀏覽器 ──（帶著你的金鑰）──→ 外部 AI API
                    ↑ 金鑰在這裡，按 F12 就看得到

✅ 本包的做法
   學生的瀏覽器 ──（不帶金鑰）──→ 你的 Netlify 函式 ──（帶金鑰）──→ 外部 AI API
                                      ↑ 金鑰只存在這裡，前端永遠碰不到

💡 兩個用途共用同一個 Netlify 帳號、同一套指令。 第二天做完 A，第三天在同一個站台上加函式即可，不用重開一個。

這包負責什麼、不負責什麼

負責

• 把一個資料夾裡的網頁推上 https://<你的站名>.netlify.app
• 讓那個網址重新部署也不會變（可以放心印 QR Code）
• 用 Netlify Functions 做一個「自己的後端」，把 API 金鑰藏在裡面
• 教你怎麼當場向老師證明金鑰真的藏起來了（F12 前後對比）

不負責

• 申請 AI／字幕服務的金鑰（09-groq-api 的範圍）。本包假設你手上已經有一把 OpenAI 相容格式的金鑰
• 資料庫、多人即時同步 → 06-supabase
• 自訂網域（xxx.edu.tw）、SSL 憑證設定
• 前端框架、打包工具（React／Vite／Next.js）。本包只處理純 HTML 資料夾

📌 和 07-github（GitHub Pages）差在哪？ GitHub Pages 只能放靜態檔案，沒有後端，所以藏不了金鑰。 需要藏金鑰 → 本包。單純放個網頁、不碰金鑰 → GitHub Pages 也可以，而且沒有點數問題。

先備條件

• 已完成 00-env-setup 與 01-connect-model（OpenCode 要能動、要接上模型）
• 有一個資料夾，裡面至少有一個 index.html
• 一個你自己收得到信的信箱（見步驟 1-4 的警告）
• 【只有用途 B 需要】手上有一把 API 金鑰

驗證：

node --version

看得到版本號就往下。看不到 → 回去做 00-env-setup。

步驟一：裝工具、開帳號

📌 研習流程裡，這一步已經在第一天下午跟著 00-env-setup 做完了。 但本包要能被單獨拿出來用，所以整段寫在這裡。已經裝好的人直接跳到 1-5。

1-1 Node.js 版本要夠新

Netlify 官方文件寫「Node 18.14 以上」，但那個數字已經過期了。 netlify-cli 套件自己的 engines 欄位要求的是：

Node.js 22.13.0 以上

以套件的要求為準，因為擋你的是它，不是文件。

node --version

⚠️ 版本不夠時的錯誤訊息長這樣，很多人看不懂： The engine "node" is incompatible with this module. Expected version ">=22.13.0" 這不是你做錯什麼，就只是 Node 太舊。

1-2 安裝 Netlify CLI

npm install -g netlify-cli

裝完先關掉終端機、重新開一個，再驗證：

netlify --version

🔴 「重開終端機」不是客套話。 剛裝好的全域指令要等 PATH 更新，而已經開著的視窗不會自己更新。 「明明裝好了卻說找不到指令」，八成就是這個。先重開再說。

1-3 🔴 Windows 會在這裡卡住：PowerShell 執行原則

裝完之後打 netlify，Windows 很可能噴這個：

netlify.ps1 cannot be loaded because running scripts is disabled on this system.

這不是你裝壞了。 npm -g 裝出來的指令在 Windows 上是一個 .ps1 腳本檔， 而 PowerShell 預設不准執行任何腳本檔。

解法（複製這一行貼上就好）：

Set-ExecutionPolicy -Scope Process -ExecutionPolicy RemoteSigned

⚠️ 每開一個新的終端機視窗都要重打一次。 這是 -Scope Process 的代價，也是它安全的原因。 覺得麻煩想改成永久的？研習現場請不要。 那是改使用者層級的安全設定， 老師回學校自己判斷就好，不要在課堂上帶著三十個人一起放寬電腦的防護。

驗證：

netlify --version

印出版本號 = 過關。

💡 macOS／Linux 沒有這個問題，直接跳過 1-3。

1-4 註冊 Netlify 帳號

🖐️ 全程在瀏覽器手動做。AI agent 不要代為註冊、不要代填密碼、不要代收驗證信。

開 https://app.netlify.com/signup。

⚠️ 學校信箱可能收不到驗證信

學校 Google Workspace / 教育網信箱常常擋掉國外服務的驗證信，而且不會退信、不會進垃圾桶，就是消失。

老師會卡在「我明明註冊了」而完全不知道發生什麼事。

研習現場的處理順序：

1. 先去垃圾郵件看一眼
2. 等 5 分鐘（有些學校信箱有延遲隔離）
3. 還是沒有 → 🔴 直接改用個人 Gmail 重註冊，不要跟學校網管耗。 一場研習卡在等網管放行，全班就停在這裡了

🔴 一人一個帳號

不要為了省事全班共用一個帳號。三個理由：

1. 300 點是整個帳號共用的。 三十個人分 300 點，等於一人 10 點，連一次正式部署都不夠
2. 部署有 API 速率限制（每分鐘 3 次），三十個人同時按下去 → 一片 429 Too Many Requests
3. 站名全球唯一，會互相撞名

1-5 讓 CLI 登入

netlify login

瀏覽器會跳出授權頁。

🖐️ 確認右上角是你自己的帳號再按 Authorize。 瀏覽器同時登著多個帳號時，很容易授權到別人身上——尤其是共用電腦的教室。

驗證：

netlify status

看得到你的 Email 和帳號名稱 = 過關。

步驟二【用途 A】把網頁推上公開網址

假設你有一個資料夾，裡面是 index.html（02-file-toolkit 或 OpenCode 做出來的都行）。

2-1 建立站台

在那個資料夾裡執行：

netlify sites:create --name class-demo-wang01 --json

🔴 站名怎麼取（這裡有兩個坑）

所以 class-demo、test、my-site 這種名字一定已經被別人用掉了，會噴：

name is taken

研習現場的取名規則：後面加上你自己的代號。 class-demo-wang01、math7-lin-0727——難聽沒關係，不會撞名比較重要。

💡 --json 是給 agent 讀的：它會把站台資訊印成 JSON，agent 可以直接抓出 name 和 url， 不用去猜終端機的文字排版。人自己打的話可以不加。

確認資料夾和站台連上了

netlify link --name class-demo-wang01
netlify status

netlify status 要看得到站名 = 連上了。

🔴 這一步不要跳過。 沒連上的話，後面 netlify env:set 會反問你「要設哪個站？」， agent 在非互動模式下會直接卡死在那個提問上，而且看起來像當機。

2-2 草稿部署（0 點，可以無限次）

netlify deploy --dir=.

--dir=. 的意思是「把現在這個資料夾當成網頁根目錄」。網頁放在 public/ 就寫 --dir=public。

跑完會印出一個 Website Draft URL，長這樣：

https://68f1a2b3c4d5e6--class-demo-wang01.netlify.app

打開它，完整檢查一遍：字有沒有跑版、按鈕會不會動、手機上看起來對不對。

🔴 這一步想試幾次就試幾次，一點都不扣。 改一行 → 再 netlify deploy → 再看。這才是正確的工作方式。

2-3 🔴 網址穩定性（決定 QR Code 能不能印）

🔴 草稿網址不能印 QR Code。

你下一次部署，那個網址就指向舊版本了（它不會壞掉，但它凍結在你當時那一版）。 貼在教室後牆的那張紙，會永遠停在你上禮拜的半成品。

要印的，只有 https://<站名>.netlify.app 這一個。

站名已經是隨機亂碼了怎麼辦

沒帶 --name 建站的話，Netlify 會給你 graceful-tartufo-8c9f71 這種名字。 QR Code 沒差（掃了都能到），但唸不出來、寫不上黑板、學生打錯字就進不來。

建議建站當下就用 --name 取好名字。 已經建成亂碼的話，去後台改：

Netlify 後台 → 選你的站 → Domain management → Options → Edit site name

改完網址立刻變成新的，舊網址就失效了——所以改名要在印 QR Code 之前做完。

2-4 正式部署（🔴 15 點，問過使用者才做）

草稿看過、確認沒問題，才執行：

netlify deploy --prod --dir=.

🔴 給 AI Agent：這一行要先問使用者。 講法建議：「草稿看起來沒問題了。要正式發布嗎？這會用掉 15 點，本月剩下的額度大約還能發布 N 次。」 使用者說「好」才執行。不准自己順手加 --prod。

跑完印出的 Website URL 就是那個永久網址。

2-5 產生 QR Code

現在才產 QR Code（網址已經固定了）：

請用 02-file-toolkit 的工具，把 https://class-demo-wang01.netlify.app 產成 QR Code 圖檔

💡 沒做過 02-file-toolkit 也沒關係，任何線上 QR 產生器都行。重點是網址要是正式的那一個。

2-6 驗證（每一項都要看到）

🔴 第 5 項每次做完都要看一眼。 這是本包唯一的煞車。

2-7 ⚠️ 備案：Netlify Drop（追進度用，不能印 QR）

有老師卡在安裝或註冊、追不上進度時，用這個讓他先看到成果：

開 https://app.netlify.com/drop → 把整個資料夾拖進去 → 30 秒後拿到一個網址。

💡 這是「讓他跟上這節課」的工具，不是「做出作品」的工具。 課後還是要回頭把步驟一～二做完。 想留住 Drop 出來的站 → 在那一小時內註冊帳號並**認領（claim）**它。

步驟三【用途 B】用 Functions 把金鑰藏在後端

3-1 🔥 教學橋段（上）：先讓大家親眼看見金鑰

這一段是整個下午的靈魂。跳過它，後面的技術細節就只是「照著打指令」。

做法：先做一個故意寫錯的版本，把金鑰直接寫在網頁裡。

<script>
  // ⚠️⚠️⚠️ 這是「錯誤示範」，等一下就要把它拆掉 ⚠️⚠️⚠️
  const API_KEY = "gsk_這裡是我的金鑰";

  async function ask(q) {
    const res = await fetch("https://api.groq.com/openai/v1/chat/completions", {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        Authorization: `Bearer ${API_KEY}`
      },
      body: JSON.stringify({
        model: "llama-3.3-70b-versatile",
        messages: [{ role: "user", content: q }]
      })
    });
    return (await res.json()).choices[0].message.content;
  }
</script>

用草稿部署上去（0 點），然後帶著全班做這兩件事：

抓法一：看原始碼（一定看得到）

F12 → 來源／Sources 分頁 → 點開 index.html → 金鑰就在那裡，明碼。

抓法二：看網路請求（更有衝擊力）

F12 → 網路／Network 分頁 → 在網頁上按一次送出 → 點那筆請求 → 標頭／Headers → 往下找 Request Headers → 看到這一行：

authorization: Bearer gsk_這裡是我的金鑰

投影出來，讓全班一起唸出來。

🔴 現場請把這句話講完整： 「這不是我設定沒做好，是前端網頁的本質。 網頁的所有程式碼都要送到學生的瀏覽器上才能執行—— 所以寫在網頁裡的東西，全世界都看得到，沒有例外。 沒有任何『加密一下』『混淆一下』能解決，那只是讓它多花三分鐘被抄走。」

🔴 三條現場紀律

1. 示範用的金鑰，用完當場作廢。 它已經在投影幕上、在錄影裡、在三十支手機的照片裡了。 示範結束就去服務商後台撤銷（revoke）並重新產一把。 🔴 刪掉檔案、刪掉部署沒有用。金鑰已經在別人手上了，換掉它才是唯一有效的處置。
2. 壞範例只用草稿部署（0 點），不要 --prod。
3. 🔴 免費方案沒有金鑰外洩偵測。 Netlify 的「Smart secret detection」是 Personal（付費）方案才有的功能。 也就是說：你把金鑰寫死在網頁裡部署上去，Netlify 不會警告你、不會擋你、不會寄信給你。 沒有安全網。這就是為什麼要靠紀律。

3-2 資料夾結構（🔴 放錯位置就是不會動）

你的專案資料夾/
├── public/                    ← 網頁放這裡（要公開的東西）
│   └── index.html
├── netlify/
│   └── functions/             ← 🔴 函式一定要在這個路徑
│       └── ask-ai.mjs         ← 🔴 副檔名一定要 .mjs
└── netlify.toml               ← 設定檔

💡 .mts 也可以（TypeScript 版）。老師用 .mjs 就好，不用學 TypeScript。

3-3 完整最小範例（三個檔，可以直接用）

✅ 以下三段程式碼都通過 node --check 語法檢查。

檔案 1／3：netlify.toml

[build]
  publish = "public"
  functions = "netlify/functions"

這個檔的作用是告訴 Netlify「網頁在哪、函式在哪」，這樣以後部署就不用每次都打一長串參數。

檔案 2／3：netlify/functions/ask-ai.mjs（🔴 金鑰藏在這裡）

// netlify/functions/ask-ai.mjs
// 前端呼叫這支函式；金鑰只存在 Netlify 伺服器上，前端永遠拿不到。

export default async (req) => {
  const json = (obj, status = 200) =>
    new Response(JSON.stringify(obj), {
      status,
      headers: { "Content-Type": "application/json; charset=utf-8" }
    });

  if (req.method !== "POST") {
    return json({ error: "只接受 POST" }, 405);
  }

  // ① 從 Netlify 的環境變數拿金鑰（不是從前端拿）
  const apiKey = process.env.AI_API_KEY;
  if (!apiKey) {
    return json({ error: "伺服器還沒設定 AI_API_KEY" }, 500);
  }

  // ② 讀前端送來的問題
  let question = "";
  try {
    const body = await req.json();
    question = String(body.question ?? "").trim();
  } catch {
    return json({ error: "請求格式不對，要送 JSON" }, 400);
  }
  if (!question) {
    return json({ error: "問題是空的" }, 400);
  }
  if (question.length > 500) {
    return json({ error: "問題太長，請縮短到 500 字以內" }, 400);
  }

  // ③ 帶著金鑰去打外部 AI API
  const upstream = await fetch("https://api.groq.com/openai/v1/chat/completions", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      Authorization: `Bearer ${apiKey}`
    },
    body: JSON.stringify({
      model: "llama-3.3-70b-versatile",
      messages: [
        { role: "system", content: "你是國中小老師的教學助理。請用繁體中文回答，200 字以內。" },
        { role: "user", content: question }
      ]
    })
  });

  if (!upstream.ok) {
    // 錯誤細節只寫進伺服器日誌，不回給前端
    console.error("上游 API 錯誤：", upstream.status, await upstream.text());
    return json({ error: "AI 服務暫時無法使用，請稍後再試" }, 502);
  }

  const data = await upstream.json();
  const answer = data.choices?.[0]?.message?.content ?? "（沒有拿到回覆）";

  return json({ answer });
};

// ④ 自訂網址：前端就用 fetch("/api/ask-ai") 呼叫
export const config = { path: "/api/ask-ai" };

這段程式碼的四個重點：

🔴 console.error 那一行的用意：外部 API 的錯誤訊息有時候會把金鑰片段回吐。 所以錯誤細節只寫進伺服器日誌（只有你看得到），前端只收到「暫時無法使用」。 不要為了好除錯就把 upstream.text() 直接回給前端——那等於白做了。

💡 換別家 API 只要改兩行：③ 的網址、和 model 名稱。 只要是 OpenAI 相容格式的服務（Groq、OpenRouter、Together……）都是同一套。 申請金鑰不在本包範圍（09-groq-api 寫好後會涵蓋）；手上有任何一把就能做這一段。

檔案 3／3：public/index.html

<!doctype html>
<html lang="zh-Hant">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>問問 AI</title>
</head>
<body>
  <h1>問問 AI</h1>
  <input id="question" placeholder="輸入你的問題" style="width:20em">
  <button id="send">送出</button>
  <pre id="answer" style="white-space:pre-wrap"></pre>

  <script>
    const btn = document.getElementById("send");
    const box = document.getElementById("question");
    const out = document.getElementById("answer");

    btn.addEventListener("click", async () => {
      const question = box.value.trim();
      if (!question) { out.textContent = "先輸入問題喔"; return; }

      btn.disabled = true;
      out.textContent = "思考中…";
      try {
        // ⬇️ 打的是「自己的網站」，不是外部 AI 服務。這裡沒有金鑰。
        const res = await fetch("/api/ask-ai", {
          method: "POST",
          headers: { "Content-Type": "application/json" },
          body: JSON.stringify({ question })
        });
        const data = await res.json();
        out.textContent = data.answer ?? ("錯誤：" + (data.error ?? "未知"));
      } catch (err) {
        out.textContent = "連線失敗：" + err.message;
      } finally {
        btn.disabled = false;
      }
    });
  </script>
</body>
</html>

🔴 整份 index.html 裡沒有任何金鑰。 這就是重點。 fetch("/api/ask-ai") 開頭的那個 / 代表「我自己這個網站」—— 學生的瀏覽器只知道要問你的網站，完全不知道背後有哪一家 AI、用哪把金鑰。

3-4 設定環境變數（兩種做法，都要會）

金鑰要放進 Netlify，不是放進檔案。兩條路，選一條。

做法 A：一個指令（適合 agent 執行）

netlify env:set AI_API_KEY "gsk_你的金鑰" --secret

🔴 要在有 netlify link 過的資料夾裡執行（步驟 2-1）。 沒連結的話它會反問你要設哪個站，agent 會卡在那個提問上。

驗證：

netlify env:list

看得到 AI_API_KEY 這個名字（值會被遮起來，這是正常的）= 過關。

做法 B：後台網頁（四步，老師回學校比較記得住）

1. Netlify 後台 → 點你的站
2. Project configuration
3. 左邊選 Environment variables
4. Add a variable → Key 填 AI_API_KEY、Value 貼金鑰 → 勾 Contains secret values → Create

💡 研習現場兩種都示範一次。 做法 A 快、可以交給 agent；做法 B 是老師三個月後自己回來換金鑰時真正會用的那一個—— 因為那時候他大概已經忘記 CLI 指令了，但後台的按鈕還在原地。

🔴 一個好消息：改金鑰不用重新部署

Netlify 官方文件寫明：Functions 範圍的環境變數，改了立刻生效，不需要重新部署。

這件事直接省你 15 點。 金鑰打錯了、金鑰要換了、換一家 AI 服務商了—— 只要改環境變數，不用 --prod。 函式下一次被呼叫就會拿到新的值。

（對照組：建置期的環境變數才需要重新部署。本包用不到那種。）

3-5 本機測試（0 點，先在這裡把錯誤都改完）

netlify dev

它會在 http://localhost:8888 起一個跟線上一模一樣的環境：網頁、函式、環境變數全部都在。

在這裡把功能測到好——送出問題、看有沒有回答、看 F12 有沒有紅字。 完全不上傳、完全不扣點。

按 Ctrl + C 結束。

3-6 部署（先草稿，再正式）

netlify.toml 已經寫好路徑了，所以指令很短：

netlify deploy

💡 沒有 netlify.toml 的話要自己帶參數： netlify deploy --dir=public --functions=netlify/functions 🔴 少了 --functions，函式不會被上傳，線上就是 404。

打開草稿網址，完整測一次（這次是真的線上環境，跟本機還是有差）。

確認沒問題才問使用者要不要正式發布：

netlify deploy --prod

3-7 🔥 教學橋段（下）：再按一次 F12

這一刻就是整個下午的收尾。

回到步驟 3-1 那個一模一樣的動作：F12 → 網路／Network → 送出一個問題 → 點那筆請求。

請把這三句話講出來：

1. 「同一個功能，一模一樣的畫面。」
2. 「剛剛全班一起唸出來的那把金鑰，現在按到底也找不到了。」
3. 「因為它在伺服器上。學生的瀏覽器從來沒拿到過它。」

🔴 前後對比才是這一段的靈魂。 只講「要用 Functions 藏金鑰」，老師點頭但不會做； 先讓他親眼看見金鑰裸奔、再親眼看見它消失，這件事他一輩子記得。 所以不要為了省時間跳過 3-1 的壞範例——那才是這節課真正在教的東西。

3-8 驗證（每一項都要看到）

🔴 第 5 項要真的做。 常見狀況：老師測試時先把金鑰寫死在某個檔案裡，改成環境變數之後忘了刪那一行， 或是留在 .env、test.html、備份.html 裡然後一起部署上去。

PowerShell 搜法（在專案資料夾執行）：

Get-ChildItem -Recurse -File | Select-String -Pattern "gsk_|sk-" | Select-Object Path, LineNumber

有結果就是還沒藏好。

為什麼不用 Vercel

同類服務裡 Vercel 最有名，但本包主線不走它。三個理由，第一個最重要。

① 🔴 免費方案（Hobby）明文禁止商業用途，而「商業」的定義踩到老師

Vercel 的 Fair Use Guidelines 白紙黑字：Hobby 方案限非商業的個人用途。 而它對「商業使用」的定義包含——

任何對參與該專案製作的人產生財務利益的部署，包括由受薪員工或顧問撰寫的程式碼。

老師是受薪員工。 你在上班時間、為了教學做的網頁，照字面就落在這個定義裡。

這是灰區，不是「一定會被停權」。但：

🔴 研習不能把三十位老師放進一個「條款上說不定不准」的位置。 老師回學校自己判斷可以；但台上教的東西必須是乾淨的。

Netlify 的免費方案沒有這條限制——教學用途明確可用。這一條就足以決定主線。

② CLI 的第一次部署強制是正式部署

Vercel 官方文件寫明：新專案的第一次部署一定是 production，就算你沒加 --prod。

也就是說：你沒有「先看看再決定」的機會。 而本包整包的核心紀律就是「先草稿、確認、才正式」——這條路直接和它牴觸。

Netlify 相反：不加 --prod 永遠是草稿，你要多看幾次就看幾次。

③ 官方 MCP 目前是唯讀

Vercel MCP 現階段只能讀（查文件、看專案、看部署紀錄），不能部署。 所以就算裝了，agent 還是得走 CLI。多裝一層卻少一半功能。

那 Vercel 什麼時候可以用

當備案：Netlify 點數用完、或 Netlify 服務中斷時的臨時出口。

🔴 但同一個專案不要換平台。 換平台 = 換網址 = QR Code 要重印 = 已經貼出去的那些全部作廢。 真的要換，在印 QR Code 之前換完。

為什麼走 CLI，不走 MCP

前面幾包（03-notebooklm、04-obsidian）都在教 MCP，這一包卻叫你打指令。原因很實際：

🔴 「官方支援清單沒有列」不等於「一定不能用」，但也不等於能用。 研習現場不賭這種事。CLI 是確定會動的那條路。

真的想試 MCP（自己在家玩，不要在研習現場）

寫進 ~/.config/opencode/opencode.json：

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "netlify": {
      "type": "remote",
      "url": "https://netlify-mcp.netlify.app/mcp",
      "enabled": true
    }
  }
}

🔴 務必自己先實測：完全關閉 OpenCode 再重開 → opencode mcp list → 對它說「列出我的 Netlify 站台」。 列得出來才算通。列不出來就回去用 CLI，不要在研習前一晚跟它耗。

⚠️ 而且要記得：MCP 也會部署，也會扣 15 點。 交給 agent 用自然語言部署很爽，但它可能在你沒注意的時候做了正式部署。 用 MCP 的話，點數紀律要講得比 CLI 更嚴。

常見坑

🔒 安全紅線（三條）

紅線一：金鑰只能存在兩個地方

✅ 可以：Netlify 的環境變數、你自己的密碼管理器。 ❌ 不可以：網頁檔案、GitHub（連私有 repo 都不要）、聊天視窗、投影片、.env 被一起部署。

紅線二：外洩的處置只有一種——換掉它

刪檔案、刪部署、改成私有、跟大家說「不要用喔」——全部無效。 🔴 去服務商後台撤銷（revoke）並重新產生。這是唯一有效的動作。

而且免費方案沒有外洩偵測，不會有人提醒你。是你自己要記得。

紅線三：函式不要把上游錯誤原封不動回給前端

外部 API 的錯誤訊息有時候會回吐金鑰片段。 範例裡用 console.error 寫進伺服器日誌、只回一句「暫時無法使用」給前端，就是為了這件事。

✅ 成功訊號（機器可判讀）

依序執行，agent 依規則判定：

node --version                 # 要 >= 22.13.0
netlify --version              # 印得出版本號
netlify status                 # 要看得到帳號與站名
netlify env:list               # 要看得到金鑰的變數名稱（用途 B 才需要）

最後輸出這一段（沒做的填 SKIP，失敗填 FAIL:<原因>）：

NETLIFY_PACK_STATUS=OK
NL_NODE=OK
NL_CLI=OK
NL_LOGIN=OK
NL_LINK=OK
NL_DRAFT=OK
NL_PROD=OK
NL_URL_STABLE=OK
NL_FN_200=OK
NL_ENV=OK
NL_NO_KEY_IN_REPO=OK
NL_NO_KEY_IN_BROWSER=OK
NL_CREDITS=OK

🔴 NL_NO_KEY_IN_REPO 或 NL_NO_KEY_IN_BROWSER 任一為 FAIL，NETLIFY_PACK_STATUS 就必須是 FAIL。 這兩項就是整個用途 B 的意義所在。不准跳過、不准「先繼續之後再補」。

🔴 NL_PROD 沒有使用者明確同意就不准執行，未執行時填 SKIP，不算失敗。

完成回報格式

## Netlify 部署結果

### 點數（🔴 每次都要回報）
- 本次正式部署（--prod）次數：<N> 次 → 消耗 <N×15> 點
- 草稿部署次數：<N> 次 → 0 點
- 後台 Usage 顯示剩餘點數：<剩餘>/300
- 本月估計還能正式部署：<約 N 次>（建議抓 15～18 次上限，不要用到見底）

### 環境
- Node.js：<版本>（需 >= 22.13.0）：PASS / FAIL
- netlify-cli：<版本>：PASS / FAIL
- Windows 執行原則已解除（本次視窗）：是 / 否 / 非 Windows
- 帳號：<email>　一人一帳號：是 / 否

### 用途 A：網頁部署
- 站名：<站名>
- 正式網址：https://<站名>.netlify.app
- 草稿網址（🔴 不可印 QR）：<url>
- 網址穩定性驗證（NL_URL_STABLE）：PASS / FAIL
- QR Code 已產生：是 / 否　→ 用的是**正式**網址：是 / 否

### 用途 B：Functions 藏金鑰
- 函式檔案：`netlify/functions/<名稱>.mjs`
- 對外路徑：`/api/<名稱>`
- 環境變數名稱：<KEY_NAME>（值未記錄，也不應記錄）
- 函式端對端測試（NL_FN_200）：PASS / FAIL / SKIP
- 🔴 專案內全文搜尋金鑰（NL_NO_KEY_IN_REPO）：PASS / FAIL
- 🔴 瀏覽器請求標頭無 Authorization（NL_NO_KEY_IN_BROWSER）：PASS / FAIL
- F12 前後對比教學橋段已完成：是 / 否 / 不適用
- 示範用的金鑰已作廢並換新：是 / 否 / 未做示範

### 安全確認
- 已告知「免費方案沒有金鑰外洩偵測，不會警告你」：是 / 否
- 已告知「金鑰外洩唯一處置是撤銷重產」：是 / 否
- 站台內沒有影片、大圖等會吃頻寬點數的檔案：是 / 否

### 待處理
- <把 FAIL 的項目與原因列在這裡；全部 PASS 就寫「無」>

如果做壞了，怎麼重來

💡 好消息：重來不用花點數。 草稿部署、失敗的部署、回滾，全都是 0 點。

🔴 回滾是 0 點，這件事要記住。 正式站發現有錯時，不要「趕快改一改再 --prod 上去」（那是 15 點）。 先回滾到上一版（0 點），把畫面救回來，然後慢慢在草稿上改到好，最後才發布一次。

下一步

• 網頁要存資料（報名、繳交、點名）→ 05-sheets-gas
• 網頁要多人同時寫（文字雲、搶答、即時排行榜）→ 06-supabase
• 專案要備份、要換電腦接得回來 → 07-github
• 要把正式網址做成 QR Code → 02-file-toolkit

📌 本包和 07-github 的分工： GitHub 存原始碼（改壞了救得回來），Netlify 負責上線（外面的人打得開）。 兩個都做，才是完整的：程式碼有備份、網址可以印。