mathruffian-dot/opencode-lazy-packs/10-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）並重新產一把。 🔴 刪掉檔案、刪掉部署沒有用。金鑰已經在別人手上了，換掉它才是唯一有效的處置。

1. 壞範例只用草稿部署（0 點），不要 --prod。
2. 🔴 免費方案沒有金鑰外洩偵測。 Netlify 的「Smart secret detection」是 Personal（付費）方案才有的功能。

也就是說：你把金鑰寫死在網頁裡部署上去，Netlify 不會警告你、不會擋你、不會寄信給你。 沒有安全網。這就是為什麼要靠紀律。

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

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