GitHub + Vercel + Neon + Dify 部署教學

GitHub + Vercel + Neon + Dify 部署教學

給第一次部署的新手:從零開始,把一個有資料庫、能接 LINE 與 AI 的網站後台放上網路。每一步都有實際操作截圖,並說明為什麼這樣選。

跟著這份教學做完,你會有一個這樣運作的系統:程式碼放在 GitHub,每次更新會自動部署到 Vercel 變成網站;資料存在 Neon 資料庫;客人從 LINE 傳訊息或填表單,資料進到你的後台;AI 交給 Dify 處理,定時工作交給 n8n。

服務白話說明這份教學用它做什麼
GitHub放程式碼的雲端倉庫,記錄每一次修改存放程式碼;更新程式時自動通知 Vercel
Vercel把程式碼變成網站的主機執行你的網站與 API,保管密碼類設定
Neon雲端資料庫(Postgres)存訂單、客戶等所有資料
Google CloudGoogle 的開發者後台讓使用者用 Google 帳號登入你的網站
LINE DevelopersLINE 的開發者後台收發 LINE 訊息、在 LINE 裡開表單(LIFF)
Dify不寫程式也能組 AI 流程的平台讓 AI 讀懂客人訊息、整理成資料
n8n自動化排程工具每天固定時間觸發工作(例如寄提醒)
[GitHub] ──程式更新──> [Vercel 你的網站與 API] ──讀寫資料──> [Neon 資料庫]
                                   ▲        ▲        ▲
              LINE 訊息 / LIFF 表單 ┘        │        └ n8n 定時呼叫
                                   Dify 呼叫 API,網站也呼叫 Dify
第 0 章

開始之前

本章目標
認識整套系統、準備帳號與軟體、先決定名稱和區域
完成後會拿到
專案名稱所有平台帳號
預估時間
30 分鐘

截圖怎麼看:本教學以一個新的空專案 tutorial-demo 示範,它的網址是 tutorial-demo.vercel.app。跟著做時,把 tutorial-demo 換成你自己的專案名稱即可。

  • 建立類的表單(建立專案、建立金鑰等)都填到「按下建立之前」為止,按鈕請你自己按。這些畫面上的值都是示範用,完整顯示。
  • 部分畫面(例如「建好之後長什麼樣子」)必須用一個已經在運作的專案才拍得到。這類畫面中屬於該專案的名稱、網址、金鑰、ID 都已打上馬賽克,只看版面和按鈕位置即可。
名詞白話解釋
Repository(repo)GitHub 上的一個專案資料夾
部署(Deploy)把程式碼變成可以連上的網站
環境變數不寫在程式碼裡的設定值,例如資料庫密碼。存在 Vercel,網站執行時讀取
Token/API Key一串長長的亂碼,當作「鑰匙」。誰拿到就能用你的服務,要當密碼保管
Production/Preview正式站/測試站。Preview 讓你在不影響客人的情況下先試新功能
Webhook對方系統有事時,主動打你的網址通知你(例如 LINE 收到訊息就通知你的網站)
API讓其他程式存取你網站功能的入口網址
MCP讓 AI 助理(如 Claude)能直接操作你系統的標準接口
區域(Region)伺服器實際放在哪個國家的機房,越近越快

需要準備的帳號(全部有免費方案):

  • GitHub:github.com
  • Vercel:vercel.com,建議直接用 GitHub 帳號登入
  • Neon:neon.tech
  • Google 帳號(用來開 Google Cloud)
  • LINE 官方帳號與 LINE Developers:developers.line.biz
  • Dify:cloud.dify.ai
  • n8n:n8n.io 雲端版,或自己架設

需要安裝在電腦上的軟體:

  • Node.js(選 LTS 版本):nodejs.org。執行和測試網站程式用。
  • Git:git-scm.com。把程式碼推上 GitHub 用。不想打指令的話,改裝 GitHub Desktop:desktop.github.com。
  • 程式編輯器:VS Code,code.visualstudio.com。

三個一開始就要決定的事:

  1. 專案名稱:所有平台都用同一個名字(例如 tutorial-demo),只用英文小寫、數字、連字號。之後看到任何平台上的名稱,就知道是哪個專案。
  2. 區域:使用者在台灣,資料庫、網站、檔案都選新加坡(Neon 叫 AWS Asia Pacific 1 (Singapore),Vercel 叫 sin1)。台灣到新加坡一趟約 40~60 毫秒,到美國東岸約 200 毫秒,一個頁面查五次資料就差將近一秒。
  3. 順序:GitHub → Neon → Vercel → Google 登入 → LINE → Dify → n8n → MCP。每一步產生的網址或金鑰,都是下一步要填的值,跳著做會一直回頭改。
第 1 章

先搞懂:密鑰、API、Webhook、MCP

本章目標
弄懂後面會出現的每一把鑰匙是什麼、怎麼流動
完成後會拿到
看懂錯誤代碼的能力
預估時間
20 分鐘

後面每一章都會產生或貼上一堆「鑰匙」,新手最常卡住的不是按鈕在哪,而是搞不清楚這把鑰匙是誰發的、給誰用、要貼到哪裡。這一章先把觀念講清楚,後面照做就不會亂。

一、三種「鑰匙」:ID、Secret、Token

種類像什麼可以公開嗎例子
ID身分證字號:告訴對方「我是誰」可以,寫在網頁前端也沒關係Google 的 Client ID、LINE 的 Channel ID、LIFF ID
Secret(密鑰)印鑑:證明「真的是我」絕對不行,只能放在伺服器(Vercel 環境變數)Google 的 Client Secret、LINE 的 Channel secret、AUTH_SECRET
Token/API Key(通行證)門禁卡:拿著它就能進門做事絕對不行Dify 的 API Key、LINE 的 Channel access token、你網站發給 Dify 的 Token

二、每一把鑰匙的一生

  1. 產生:在發行的平台上按「建立」,通常只顯示一次,關掉視窗就看不到了。
  2. 保存:立刻存進密碼管理器(1Password、Bitwarden、iCloud 鑰匙圈),再貼到要用它的地方。
  3. 使用:程式從環境變數讀出來,放在請求裡送出去。
  4. 輪替:定期或懷疑外流時,產生一把新的、換上去、確認正常,再把舊的作廢。
  5. 撤銷:不用了或確定外流,到發行的平台按刪除/Revoke,舊鑰匙立刻失效。

三、API:別人怎麼使用你的網站功能

API 就是一個「專門給程式用的網址」。人用瀏覽器看網頁,程式用 API 拿資料或叫網站做事。一次 API 呼叫長這樣:

POST https://tutorial-demo.vercel.app/api/v1/orders     ← ① 方法 + 網址:要做什麼、找誰
Authorization: Bearer tk_demo_3f9a7c21...               ← ② 鑰匙:證明你有權限
Content-Type: application/json                          ← ③ 資料格式
Idempotency-Key: run-20261024-001                       ← ④ 防重複:同一個值只會執行一次

{ "name": "王小明", "phone": "0912345678", "date": "2026-11-01" }   ← ⑤ 內容
方法意思例子
GET讀取查訂單
POST新增/執行建立訂單、觸發排程
PATCH/PUT修改改訂單狀態
DELETE刪除刪訂單

Bearer 是什麼:Authorization: Bearer <Token> 是業界最常見的帶鑰匙方式。Bearer 是固定的英文字,意思是「持有者」,後面空一格接 Token。整串放在 Header(請求的信封上),不放在網址裡,因為網址會被記錄在各種日誌中。

對方回應的狀態碼,看懂它就能自己排錯:

狀態碼意思通常是哪裡錯
200/201成功—
400你送的資料格式不對少了必填欄位、日期格式錯
401沒帶鑰匙或鑰匙錯Token 貼錯、多了空白、Bearer 寫兩次、Token 過期
403鑰匙對,但權限不夠這把 Token 沒有勾這項權限
404找不到網址打錯、路徑少一段
429呼叫太頻繁超過每分鐘上限,等一下再試
500/502/503對方伺服器出錯看 Vercel 的 Runtime Logs,或環境變數沒設

四、Webhook:反過來,別人主動通知你

API 是「你去問對方」;Webhook 是「對方有事主動打給你」。LINE 收到客人訊息時,會主動把訊息送到你網站的某個網址,這個網址就叫 Webhook URL。

APIWebhook
誰發起你(或 Dify、n8n)主動呼叫對方平台(LINE)主動呼叫你
怎麼證明身分呼叫的人帶 Token對方附上簽章,你用 Secret 驗證
例子Dify 呼叫 /api/v1/orders 建單LINE 呼叫 /api/line/webhook 送訊息

簽章怎麼運作:LINE 和你的網站都知道同一個 Channel secret。LINE 送訊息時,用這個 Secret 對內容算出一段簽章附在 Header;你的網站收到後用同一個 Secret 再算一次,兩邊一樣才相信是 LINE 送的。所以 Channel secret 填錯,Webhook 一定驗證失敗。

五、MCP:讓 AI 助理會用你的系統

MCP(Model Context Protocol)可以想成「AI 專用的插座」。你的網站提供一個 MCP 網址,裡面列出一組「工具」(例如查訂單、建訂單),每個工具附上說明。Claude、Dify 這類 AI 連上後,會自己讀說明、判斷什麼時候該用哪個工具。

APIMCP
給誰用工程師寫的程式AI 助理
怎麼知道有哪些功能看說明文件(OpenAPI),手動設定連上後自動取得工具清單與說明
誰決定呼叫哪個功能程式碼寫死AI 依對話內容自己判斷
認證Bearer Token一樣用 Bearer Token(或 OAuth 登入)

兩個角色:提供工具的一方叫 MCP 伺服器(你的網站 /api/mcp、Vercel、Neon、GitHub 官方都有);使用工具的一方叫 MCP 客戶端(Claude、Claude Code、Dify)。

六、一則 LINE 訊息走過的完整路線

把所有鑰匙串起來看。客人在 LINE 傳「11/1 早上 4 個人去機場」,系統裡發生的事:

  1. 1
    LINE 平台客人的訊息送到你的 Webhook URL,附上簽章
    不需要鑰匙
  2. 2
    你的網站(Vercel)用 Channel secret 驗證簽章,確認真的是 LINE 送的
    LINE_CHANNEL_SECRET
  3. 3
    你的網站 → Dify把訊息文字交給 Dify 工作流整理
    DIFY_API_KEY
  4. 4
    DifyAI 讀懂內容,整理出日期、人數、地點
    不需要鑰匙
  5. 5
    Dify → 你的網站呼叫網站 API 建立訂單
    你網站發給 Dify 的 Token
  6. 6
    你的網站 → Neon把訂單寫進資料庫
    DATABASE_URL
  7. 7
    你的網站 → LINE回覆客人「已收到,稍後報價」
    LINE_CHANNEL_ACCESS_TOKEN

七、最容易搞混的成對名詞

容易搞混差別記法
Client ID vs Client Secret(Google)ID 可公開,填 Config;Secret 是密碼,填 SecretID 是名字,Secret 是密碼
Channel ID vs Channel secret vs Channel access token(LINE)ID 是編號;secret 用來驗證 LINE 送來的訊息;access token 用來發送訊息給客人收訊息用 secret,發訊息用 token
Channel ID vs LIFF ID(LINE)Channel ID 是一串數字;LIFF ID 是「Channel ID-一段英數字」LIFF ID 比較長,有連字號
Messaging API vs LINE Login(LINE)前者收發聊天訊息;後者讓客人在網頁登入(LIFF 放在這裡)聊天 vs 表單
Pooled vs Direct 連線(Neon)Pooled 主機名稱有 -pooler,網站平常用;Direct 沒有,建資料表用網站用 pooled,migration 用 direct
Production vs Preview(Vercel)正式站 vs 測試站,環境變數各自獨立設變數時要勾對環境
Secret vs Config(Vercel 環境變數類型)Secret 存了就看不到;Config 之後還看得到會讓人做壞事的值選 Secret
Dify API Key vs 你網站的 Token前者是 Dify 發給你、讓你呼叫 Dify;後者是你網站發給 Dify、讓 Dify 呼叫你誰發的就是誰的門禁卡
Swagger 工具的 Bearer vs MCP 的標題(Dify)Swagger 工具會自動加 Bearer ,值只貼 Token;MCP 標題不會,值要自己寫 Bearer xxx兩邊相反,最容易 401
Webhook URL vs Endpoint URL(LINE)Webhook 是 LINE 送訊息到你網站的網址;LIFF 的 Endpoint 是客人打開的網頁網址一個給 LINE 打,一個給人看
工作流 vs 聊天流(Dify)一問一答 vs 多輪對話,呼叫網址不同整理資料用工作流
API vs MCPAPI 給程式用;MCP 給 AI 用(背後還是呼叫 API)MCP 是 API 的 AI 版插座
第 2 章

GitHub:建立程式碼倉庫

GitHub 是放程式碼的雲端倉庫,每次修改都有紀錄、可以退回。Vercel 會盯著它,程式一更新就自動部署。

本章目標
建立私人 repo、把程式推上去、保護 main 分支
完成後會拿到
repo 網址
預估時間
20 分鐘

免費方案免費方案可以建無限個私人 repo,個人使用完全夠。

2.1

開啟建立 Repository 頁面

GitHub 建立新 Repository 的空白表單

操作

  1. 登入 GitHub,點右上角 + → New repository,或直接開 github.com/new。

為什麼這樣做

  • Repository 是整套部署的起點:Vercel 會監看它,程式一更新就自動重新部署。
2.2

可見度選 Private

Choose visibility 下拉選單,Public 與 Private

操作

  1. Owner 保持自己的帳號。
  2. Repository name 輸入 tutorial-demo,下方出現綠色 is available 代表名稱可用。
  3. Description 寫一句這個專案在做什麼。
  4. 點 Choose visibility 右側的 Public,改選 Private。

為什麼這樣做

  • 商業系統的程式碼裡有資料表結構、API 路徑、權限邏輯,公開等於把系統弱點攤給所有人看。
  • Private 一樣能免費連 Vercel 自動部署,沒有理由選 Public。
  • 已經建成 Public 的 repo,可以到 repo 的 Settings → General → 最下方 Danger Zone → Change visibility 改成 Private,不影響部署。
2.3

.gitignore:先判斷你有沒有現成的程式

.gitignore 範本搜尋框輸入 Node

操作

  1. 電腦裡還沒有程式(要從零開始寫):Add .gitignore 搜尋 Node,選 Node。
  2. 電腦裡已經有程式(別人給你、AI 幫你寫好的):Add README、Add .gitignore、Add license 全部保持預設的「不加」,建立一個空的 repo。
  3. Add license 一律保持 No license。

為什麼這樣做

  • .gitignore 是一份「不要上傳的檔案清單」。Node 範本會排除 node_modules/(套件,動輒數百 MB)和 .env(密碼檔)。
  • 已經有程式的人如果在這裡多加了檔案,等一下第一次上傳會出現 rejected 錯誤,因為雲端和電腦上的版本對不起來。新手最常卡在這一步。
  • 密碼一旦被上傳到 GitHub,就算事後刪掉,也還留在修改紀錄裡,只能把密碼作廢重發。
  • 私人商業專案不需要開源授權。
2.4

核對後建立

填寫完成:名稱、Private、Node、No license

操作

  1. 核對:名稱、Private、.gitignore 的選擇、No license,按 Create repository。

為什麼這樣做

  • 名稱之後會出現在網站網址、Google 登入設定、LINE 設定裡。建立前就定案,改名會牽動很多地方。
2.5

程式上傳後的 repo 頁面

範例 repo 首頁:名稱旁顯示 Public,檔案清單有 .env.example、.gitignore、vercel.json

操作

  1. 上傳完成後,重新整理 repo 頁面,會看到檔案清單。
  2. 確認三件事:名稱旁的標籤是 Private;清單裡有 .gitignore 和 .env.example;清單裡沒有 .env 或 .env.local。

為什麼這樣做

  • 這個範例的標籤是 Public,就是需要改成 Private 的情況(下面示範)。
  • 看到 .env 出現在清單裡,代表密碼已經外流,要立刻把裡面每一組密碼到各平台作廢重發,光刪檔沒用。
2.6

已經是 Public?改成 Private

Settings > General 最下方 Danger Zone,Change visibility 展開 Change to private

操作

  1. repo 上方 Settings(在 More 裡)→ 左側 General → 拉到最下方 Danger Zone。
  2. Change repository visibility → Change visibility → Change to private。
  3. 跳出確認視窗,照指示輸入 repo 名稱後確認。

為什麼這樣做

  • 改成 Private 不影響 Vercel 自動部署,Vercel 已經透過授權讀得到。
  • Danger Zone 裡其他按鈕(轉移、封存、刪除)都不要碰。
2.7

把電腦裡的程式推上 GitHub

方法一:GitHub Desktop(不用打指令)

  1. 開 GitHub Desktop,登入 GitHub 帳號。
  2. File → Add local repository,選你的專案資料夾。出現「不是 Git repository」的提示時,按 create a repository。
  3. 左下角 Summary 填「第一次上傳」,按 Commit to main。
  4. 按上方 Publish repository,勾選 Keep this code private,按 Publish。

方法二:終端機指令(在專案資料夾內執行,把 <帳號> 換成你的 GitHub 帳號)

git init
git add .
git commit -m "第一次上傳"
git branch -M main
git remote add origin https://github.com/<帳號>/tutorial-demo.git
git push -u origin main
2.8

專案裡要有的兩個設定檔

.gitignore 內容:第 34 行 .env* 排除所有 env 檔,第 37 行 .vercel,第 45 行 !.env.example 例外放行

操作

  1. 在 GitHub 點 .gitignore 檔案就能看到內容。這是一個 Next.js 專案的範例。
  2. 確認有 .env*(第 34 行):排除所有以 .env 開頭的檔案,包括 .env、.env.local、.env.production。
  3. 確認有 .vercel(第 37 行):Vercel 工具在你電腦上產生的連結設定,不該上傳。
  4. 確認有 !.env.example(第 45 行):開頭的 ! 代表「例外,這個要上傳」。

為什麼這樣做

  • 用 .env* 一次排除全部,比一個一個列安全:日後多了新的 env 檔也會自動被擋下。但這樣也會擋掉 .env.example,所以要再加一行 ! 例外。

再建立一個 .env.example,列出網站需要的所有設定名稱,但值留空。這個檔案要上傳到 GitHub。

# .env.example(範例,實際名稱依你的程式而定)
DATABASE_URL=
DATABASE_URL_UNPOOLED=
AUTH_SECRET=
AUTH_GOOGLE_ID=
AUTH_GOOGLE_SECRET=
APP_BASE_URL=
LINE_CHANNEL_SECRET=
LINE_CHANNEL_ACCESS_TOKEN=
DIFY_API_KEY=
CRON_SECRET=
2.9

分支是什麼、為什麼要用

  • main 分支 = 正式網站。main 一有更新,Vercel 就更新正式網站。
  • 要改新功能時,另開一個分支(例如 feature-booking)在上面改。推上 GitHub 後,Vercel 會自動產生一個測試網址(Preview)。
  • 在測試網址確認沒問題,再合併回 main。
2.10

保護 main 分支:建立規則

New branch ruleset:Ruleset Name protect-main,Enforcement status 下拉 Active、Disabled

操作

  1. repo 的 Settings → 左側 Rules → Rulesets → New ruleset → New branch ruleset。
  2. Ruleset Name:protect-main。
  3. Enforcement status:預設是 Disabled,要改成 Active。

為什麼這樣做

  • 沒有保護的話,一個打錯的指令(例如強制推送)就能把 main 的歷史紀錄蓋掉,正式網站也跟著壞掉。
  • 預設 Disabled 代表規則建了也不生效,這是最常被忽略的一格。
2.11

指定要保護的分支

Target branches 的 Add target 選單:Include default branch、Include all branches、Include by pattern

操作

  1. Target branches → Add target → Include default branch。

為什麼這樣做

  • 預設分支就是 main。選這個,日後就算把預設分支改名,規則也會自動跟著走。
2.12

勾選規則

Branch rules:Restrict deletions 與 Block force pushes 已勾選

操作

  1. 確認 Restrict deletions(禁止刪除分支)與 Block force pushes(禁止強制推送)有勾選,這兩個是預設勾好的。
  2. 一個人開發時先不要勾 Require a pull request before merging,否則你自己也無法直接推到 main。
  3. 拉到最下面按 Create。

為什麼這樣做

  • 這兩條規則擋住的是「無法復原」的操作,對日常開發完全沒有影響,是最划算的保險。等有協作者時,再加上「必須透過 PR 合併」。
第 3 章

Neon:建立資料庫

Neon 是雲端的 Postgres 資料庫,特色是可以像 Git 一樣開「分支」,把正式資料和測試資料分開。

本章目標
建立資料庫、開 preview 分支、拿到連線字串
完成後會拿到
DATABASE_URL(正式、測試各一)DATABASE_URL_UNPOOLED(正式、測試各一)
預估時間
15 分鐘

免費方案免費方案有儲存容量與運算時數上限,閒置會自動休眠。上限數字以 Neon 定價頁為準。

3.1

專案列表

Neon 專案列表,所有專案都在 AWS Asia Pacific 1 (Singapore)

操作

  1. 登入 console.neon.tech,右上角黑色 ⊕ 是建立專案。

為什麼這樣做

  • 一個網站系統對應一個 Neon 專案。不同專案的資料、密碼、用量完全分開,一個出事不會影響另一個。
3.2

專案名稱與區域

Region 下拉選單,預設 AWS US East 2 (Ohio)

操作

  1. Project name 輸入 tutorial-demo。
  2. Region 預設是 AWS US East 2 (Ohio),一定要改成 AWS Asia Pacific 1 (Singapore)。

為什麼這樣做

  • 區域建立後不能更改,選錯只能整個重建、搬資料。
  • 預設的美國機房,對台灣使用者每次查資料多 150 毫秒以上,後台操作會明顯卡頓。
3.3

服務只開 Postgres

Postgres database 開啟,Database name,Postgres version 18,其他服務關閉

操作

  1. Postgres database 保持開啟。展開後 Database name 可改成專案名稱,Postgres version 用預設。
  2. Object storage、Functions、AI gateway、Realtime、Better Auth 全部保持關閉。
  3. 按 Create project。

為什麼這樣做

  • 這份教學的檔案存 Vercel、登入用 Google、AI 用 Dify,這些 Neon 附加服務都用不到。多開一項,就多一套要記得的設定。
  • 資料庫名稱改成專案名稱,日後看到連線字串就知道連的是哪個系統。
3.4

分支:把正式資料和測試資料分開

兩個分支:production(Default)、preview

操作

  1. 左側 Branches。新專案會有一個預設分支,範例專案把它命名為 production,另外建了 preview。

為什麼這樣做

  • Neon 的分支是資料庫的一份即時複本,建立只要一秒,沒改資料前不占空間。
  • 測試網站接 preview 分支,測試時新增、刪除資料都不會碰到正式資料。
3.5

建立 preview 分支

Create new branch 對話框,Auto-delete 預設 After 1 day

操作

  1. Branches 頁右上 ⊕。

為什麼這樣做

  • 注意 Auto-delete(自動刪除)預設是 After 1 day。這是給臨時測試用的,我們要長期使用,必須改掉。
3.6

Auto-delete 改成 Never

Auto-delete 下拉:Never、After 1 hour、After 1 day、After 7 days、Custom

操作

  1. Name 輸入 preview。
  2. Auto-delete 改選 Never。

為什麼這樣做

  • 保留預設的話,這個分支隔天就被自動刪掉,測試網站會突然全部連不上資料庫,錯誤訊息還不會告訴你原因。
3.7

父分支與複製方式

Name preview、Auto-delete Never、Parent branch production、Branch data and schema

操作

  1. Parent branch 選正式分支。
  2. 保持 Branch data and schema(複製資料和結構)。
  3. 按 Create。

為什麼這樣做

  • 複製完整資料,測試時才有真實的價目表、車型等設定可用。
  • 正式資料有很多客人個資、又有別人會用測試站時,改選 Branch & anonymize data,個資會被自動遮蔽。
3.8

資料庫會自動休眠

Computes 頁面,狀態 SUSPENDED,右側 Connect 按鈕

操作

  1. 分支頁左側 Computes。SUSPENDED 代表目前休眠中。

為什麼這樣做

  • 免費方案閒置約 5 分鐘就會休眠省額度。休眠後第一次查詢要多等 0.5~1 秒喚醒,之後就正常。早上第一次打開網站比較慢是正常現象,不是壞掉。
3.9

複製連線字串(一):給網站平常使用

Connection details,Connection pooling 開啟,主機名稱含 -pooler

操作

  1. Computes 頁點 Connect。
  2. Branch 確認是正式分支,Database、Role 用預設。
  3. Connection pooling 開啟(主機名稱會出現 -pooler),按 Copy snippet。
  4. 先貼到記事本,標註「正式 pooled」。等一下要填到 Vercel 的 DATABASE_URL。

為什麼這樣做

  • Vercel 同時可能有很多個網站程式在跑,每個都要連資料庫。不經過連線池(pooling),人一多就會撞到資料庫的連線上限。
  • 連線池會把大量短暫的連線合併成少數幾條,Vercel 這類環境一定要開。
3.10

複製連線字串(二):給資料表建立工具

Connection pooling 關閉,主機名稱沒有 -pooler

操作

  1. 把 Connection pooling 關閉,再複製一次,標註「正式 direct」,之後填到 DATABASE_URL_UNPOOLED。
  2. Branch 切到 preview,同樣各複製一組。
  3. 最後記事本裡會有四組:正式 pooled、正式 direct、preview pooled、preview direct。

為什麼這樣做

  • 建立資料表、新增欄位(稱為 migration)需要一條穩定的直接連線。走連線池會出現莫名其妙的失敗。
3.11

確認資料表有建立

Tables 頁面列出資料表

操作

  1. 網站第一次部署並執行 migration 後,左側 Tables 會看到資料表清單。

為什麼這樣做

  • 看到資料表就代表網站連得上資料庫、也成功建表了。之後要改資料表結構,一律透過程式的 migration,不要在這個頁面手動改,否則程式和資料庫會對不上。
3.12

保護正式分支

Settings 頁,Branch protection 顯示 Not protected

操作

  1. Settings → General → Branch protection → 對正式分支按 Protect this branch。

為什麼這樣做

  • 受保護的分支不能被刪除或重設。之後讓 AI 助理幫忙管資料庫時,這是防止它誤刪正式資料的最後一道保險。
3.13

Neon API Key(之後給 AI 助理用)

組織設定 API keys 頁

操作

  1. 右上頭像 → Settings → API keys。現在用不到可以先跳過,「MCP」章會用到。

為什麼這樣做

  • 讓 Claude 等 AI 助理直接管理 Neon 時,可以用 OAuth 登入(推薦)或給一把 API Key。用 Key 時一定要限制範圍。
3.14

建立「只限一個專案」的 API Key

Create new API key:Key scope 選 Project-scoped

操作

  1. Create new API key。
  2. Key scope 改選 Project-scoped,Project 選 tutorial-demo。
  3. Key name 寫用途,例如 claude-tutorial-demo。
  4. 按 Create。Key 只顯示這一次,立刻存進密碼管理器。

為什麼這樣做

  • 預設的 Org-wide 能管理你所有的 Neon 專案,包括刪除。外流了,所有專案都有危險。
  • 名稱寫清楚給誰用,日後要停用時才知道刪哪一把。
第 4 章

Vercel:把網站部署上線

Vercel 把 GitHub 上的程式碼變成一個可以連上的網站,並幫你保管所有密碼類設定(環境變數)。

本章目標
部署網站、設定環境變數、指定新加坡區域、建立檔案儲存
完成後會拿到
網站網址 tutorial-demo.vercel.appBLOB_READ_WRITE_TOKEN
預估時間
30 分鐘

免費方案免費的 Hobby 方案僅限個人、非商業用途。網站用於公司營運或收費服務,要升級 Pro 方案。

4.1

匯入 GitHub 上的專案

Vercel New Project 頁,Import Git Repository 清單

操作

  1. 開 vercel.com/new。
  2. Import Git Repository 左側確認是你的 GitHub 帳號,找到 tutorial-demo 按 Import。
  3. 清單裡找不到 repo:點帳號下拉 → Adjust GitHub App Permissions,到 GitHub 頁面選 Only select repositories,把 tutorial-demo 加進去。

為什麼這樣做

  • Vercel 要有權限讀你的 repo 才能部署。授權時選「只給指定的 repo」,不要給全部。
  • 清單中名稱旁邊有鎖頭的是 Private repo,沒有鎖頭的是 Public。
4.2

檢查 Vercel 能讀哪些 repo

GitHub 設定 > Applications > Vercel:Repository access 目前選 All repositories

操作

  1. GitHub 右上頭像 → Settings → 左側 Applications → Installed GitHub Apps → Vercel 右側 Configure,拉到 Repository access。

為什麼這樣做

  • 範例畫面是 All repositories:Vercel 可以讀寫你所有 repo,包括未來新建的。上方 Permissions 寫明它有程式碼的讀寫權限。
  • 萬一 Vercel 帳號被盜,所有程式碼都會受影響。
4.3

改成只授權指定的 repo

Repository access 改選 Only select repositories,出現 Select repositories 按鈕

操作

  1. 改選 Only select repositories。
  2. 按 Select repositories,把要部署的 repo 一個一個加進來。
  3. 按 Save。

為什麼這樣做

  • 只開放需要部署的 repo,其他 repo 就算 Vercel 出事也不受影響。之後每多一個要部署的專案,回來這裡加一個即可。
4.4

專案名稱、根目錄、框架

New Project 設定頁,Project Name 被自動加上亂碼字尾

操作

  1. Vercel Team 選自己的(免費方案顯示 Hobby)。
  2. Project Name:預設是 repo 名稱;如果名稱已被別人使用,Vercel 會自動加一段亂碼字尾,請改成你要的名稱。
  3. Root Directory 保持 ./;Application Preset 確認自動偵測到你的框架(範例是 Next.js)。

為什麼這樣做

  • 專案名稱決定網址 <名稱>.vercel.app。這個網址之後要填到 Google、LINE 好幾個地方,帶亂碼很容易抄錯。
  • Root Directory 只有一個 repo 裡放多個專案時才需要改。
4.5

建置設定保持預設

Build Command、Output Directory、Install Command 皆為預設

操作

  1. 展開 Build and Output Settings,確認三個欄位都是灰色預設文字,右側開關都不要打開。

為什麼這樣做

  • Vercel 會自動判斷怎麼建置。手動改過之後,日後升級套件容易出錯,而且你通常已經忘了自己改過。
4.6

第一次部署前先填環境變數

Environment Variables 區塊,Key、Value、Environments

操作

  1. 展開 Environment Variables。可以一筆一筆填,也可以按 Import .env 上傳整份。
  2. 至少先填:DATABASE_URL(正式 pooled)、DATABASE_URL_UNPOOLED(正式 direct)、AUTH_SECRET(產生方式見「環境變數總表」章)。
  3. 按 Create Project / Deploy,等一兩分鐘。

為什麼這樣做

  • 網站一啟動就要連資料庫。缺了這幾個值,第一次部署一定失敗。先填好,第一次就能成功,比較不會挫折。
4.7

環境變數清單

Environment Variables 清單,有 T、鎖頭、<> 三種圖示

操作

  1. 之後要新增或修改,進專案 Settings → Environment Variables。

為什麼這樣做

  • 左側圖示:T 是一般設定(看得到值);鎖頭是機密(存了就看不到);<> 是 Vercel 整合服務自動建的。
  • 某一筆旁邊出現黃色標記,代表 Vercel 建議你把它改成機密類型。
4.8

新增環境變數:選機密或一般

Add Environment Variable 對話框,Type 有 Secret 與 Config

操作

  1. 按 Add Environment Variable。
  2. 密碼、Token、金鑰、連線字串 → 選 Secret。
  3. 網址、Email、各平台的 ID → 選 Config。

為什麼這樣做

  • Secret 存進去之後誰都看不到,包括你自己。萬一 Vercel 帳號被盜,對方也讀不出來。要換值就直接覆蓋,原本的值應該保存在你的密碼管理器裡。
4.9

填名稱、值、備註

Key LINE_CHANNEL_SECRET,Note 填寫來源位置

操作

  1. Key:名稱必須和程式碼裡讀取的一字不差,包含大小寫(例如 LINE_CHANNEL_SECRET)。
  2. Value:貼上值。注意前後不能有空白或換行。
  3. Note:寫這個值在哪個平台、哪一頁產生的,例如 LINE Developers > Messaging API > Basic settings。
  4. Environments 點開 → Environments。

為什麼這樣做

  • 從網頁複製時很常多帶一個換行,結果驗證永遠失敗,錯誤訊息只會說「不符」,很難查。
  • 備註是寫給未來要更換金鑰的自己,省得翻遍每個平台找來源。
4.10

勾選要套用的環境

Production 已勾選,Preview、Development 未勾選

操作

  1. LINE、Dify、Google 這類正式服務的金鑰:只勾 Production。
  2. 資料庫:Production 與 Preview 分開新增兩次,各填對應 Neon 分支的值。
  3. 要在自己電腦上開發用的值:勾 Development。
  4. 按 Save。然後到 Deployments 頁,對最新一筆按 ⋯ → Redeploy。

為什麼這樣做

  • 測試站如果也用正式的 LINE 金鑰,測試時可能真的發訊息給客人。
  • 改了環境變數不會自動生效,一定要重新部署。 這是新手最常遇到的「明明設了卻沒作用」。
4.11

確認網站跑在新加坡

Functions 設定頁,Function Region

操作

  1. Settings → Functions → Function Region。

為什麼這樣做

  • 網站程式要和資料庫在同一區。這個範例畫面顯示美國東岸 iad1,但標題旁邊有黃色 Overridden,表示實際值被其他設定蓋掉了,下兩步說明。
4.12

Overridden 是什麼

滑鼠移到 Overridden:此設定被 vercel.json 覆寫

操作

  1. 滑鼠移到 Overridden 上,點 View Override。

為什麼這樣做

  • 專案裡的 vercel.json 設定檔,優先權高於這個頁面。頁面上改了卻沒效果,多半是被這個檔案蓋掉。
4.13

用 vercel.json 指定新加坡

vercel.json 內容 regions: [sin1]

操作

  1. 在專案根目錄建立 vercel.json,內容如下,推上 GitHub:

為什麼這樣做

  • 寫在檔案裡,設定會跟著程式碼走。換專案、重建專案都不會忘記設。
{
  "$schema": "https://openapi.vercel.sh/vercel.json",
  "regions": ["sin1"]
}
4.14

或在頁面上選區域

Asia Pacific 展開:hkg1、hnd1、icn1、sin1、bom1、syd1

操作

  1. 沒有 vercel.json 的話:展開 Asia Pacific,勾 Singapore (Southeast) - sin1,按 Save,再重新部署。

為什麼這樣做

  • 免費方案只能選一個區域。Neon 沒有香港和東京機房,選新加坡才會和資料庫同區。
4.15

檔案儲存(Blob)

Storage 頁,已有一個 Blob Store 標示 Public

操作

  1. 網站需要讓人上傳檔案(照片、證件、單據)時,到專案的 Storage 頁。

為什麼這樣做

  • Vercel 的網站程式每次重新部署,電腦裡的檔案就清空,上傳的檔案一定要存在 Blob 這類外部空間。
  • 注意範例中的 Store 標示 Public:網址外流任何人都能下載。存客人資料要用 Private,下面示範。
4.16

選擇 Blob

Browse Storage 清單

操作

  1. Create Storage → 選 Blob → Continue。

為什麼這樣做

  • 資料庫已經用 Neon,這裡只要存檔案,不要再從清單裡多加一個資料庫。
4.17

Blob 預設值有兩個要改

Create Blob Store:Region 預設 iad1

操作

  1. Region 預設是美國 iad1,畫面上寫明建立後不能改。

為什麼這樣做

  • 選錯只能刪掉重建、再把檔案搬過去。
4.18

Blob 設定完成

Store Name、Region sin1、Access Private、勾選 read-write token

操作

  1. Store Name:tutorial-demo-files。
  2. Region:Singapore (Southeast) – sin1。
  3. Access:Private。
  4. 勾選 Add a read-write token env var to this connection。
  5. 按 Create。

為什麼這樣做

  • Private 要有 Token 才能讀檔,客人上傳的資料不會因為網址外流被下載。
  • 勾選後 Vercel 會自動建立 BLOB_READ_WRITE_TOKEN 環境變數,不用自己複製。
  • 畫面中的紅字是因為範例專案已經有一個 Blob,名稱會衝突,才需要填前綴。第一次建立的人不會看到。
4.19

GitHub 連動設定

Connected Git Repository,Pull Request Comments 開啟

操作

  1. Settings → Git,確認連到正確的 repo,Pull Request Comments 與 Commit Status 保持開啟。

為什麼這樣做

  • 之後在 GitHub 發 PR,頁面上會自動出現測試網址和部署結果,不用切回 Vercel 查。
4.20

三個環境

Environments:Production 追蹤 main,Preview 追蹤其他分支,Development 透過 CLI

操作

  1. Settings → Environments。

為什麼這樣做

  • Production 跟著 main 分支;其他分支都是 Preview;Development 是你自己電腦上的開發環境。
  • 環境變數就是依這三個環境分開設的。下方 Custom Environments 要付費,用不到。
4.21

網域

Domains 頁,預設 .vercel.app 網址

操作

  1. Settings → Domains。預設已經有 tutorial-demo.vercel.app。

為什麼這樣做

  • 之後綁自己買的網域,記得同步更新:環境變數 APP_BASE_URL、Google 登入的網址、LINE 的 Webhook 和 LIFF 網址。
4.22

給測試站一個固定網址

Add Domains:輸入 preview 網域,Connect to an environment

操作

  1. Add Existing → 輸入 preview.你的網域。
  2. Connect to an environment 下拉改為 Preview,再選要對應的分支。
  3. 按 Add Domain,照畫面指示到網域商新增 DNS 紀錄。

為什麼這樣做

  • 測試站網址每次都不一樣,但 Google 登入和 LINE 都要求事先登記網址。給測試站一個固定網址,才能在測試站測登入和 LINE。沒有自己的網域可以先跳過,只在正式站測。
4.23

排程(Cron)為什麼交給 n8n

Cron Jobs 設定頁

操作

  1. Settings → Cron Jobs。這裡是 Vercel 內建排程,在 vercel.json 設定。

為什麼這樣做

  • 免費方案的 Vercel 排程次數很有限,無法做到每 15 分鐘一次。需要頻繁執行的工作改用 n8n 定時呼叫你的網站(見「n8n」章)。
4.24

部署紀錄與退版

Deployments 清單,每筆皆為 Ready

操作

  1. Deployments 頁,每一次部署都會留一筆紀錄。
  2. 部署失敗(紅色 Error):點進去看 Build Logs,錯誤通常在最後幾行。
  3. 新版有問題:對上一個正常的版本按 ⋯ → Promote to Production,幾秒內就退回舊版。

為什麼這樣做

  • 每次部署都完整保存,出事可以一鍵退版,先止血再慢慢查原因。
4.25

在自己電腦上取得環境變數

npm i -g vercel
vercel login
vercel link          # 在專案資料夾內執行,選擇對應的 Vercel 專案
vercel env pull .env.local
第 5 章

Google Cloud:讓後台可以用 Google 帳號登入

Google Cloud 是 Google 的開發者後台。這裡只用到其中一個功能:讓使用者用 Google 帳號登入你的網站(OAuth)。

本章目標
建立 OAuth 用戶端、設定誰可以登入
完成後會拿到
AUTH_GOOGLE_IDAUTH_GOOGLE_SECRET
預估時間
20 分鐘

免費方案Google 登入功能免費,不需要綁信用卡也能用。

這一章會拿到兩個值:AUTH_GOOGLE_ID 與 AUTH_GOOGLE_SECRET。你的網站程式需要有「使用 Google 登入」功能,現成的工具有 Auth.js、Better Auth 等。

5.1

使用者看到的登入流程

範例後台的登入頁,使用 Google 帳號登入按鈕

為什麼這樣做

  • 使用者按下按鈕 → 跳到 Google → 登入後 Google 帶著一個「通行碼」回到你的網站(這個網址叫回呼網址)。下面的設定就是告訴 Google:這個網址是我的,請把通行碼送到這裡。
5.2

Google 的選擇帳戶畫面

使用 Google 帳戶登入,繼續使用範例網址

為什麼這樣做

  • 設定正確時會看到這個畫面,上面寫著你的網站網址。如果看到的是錯誤頁,寫著 redirect_uri_mismatch,就是下面的「重新導向 URI」沒填對。
5.3

建立 Google Cloud 專案、進入憑證頁

API 和服務 > 憑證頁面

操作

  1. 開 console.cloud.google.com。第一次使用時,左上角點專案選擇器 → 新增專案 → 名稱填 tutorial-demo → 建立。
  2. 確認左上角已切換到 tutorial-demo。
  3. 左側選單 API 和服務 → 憑證。

為什麼這樣做

  • 一個網站系統一個 Google Cloud 專案,登入設定和其他專案互不干擾。
5.4

設定登入同意畫面(第一次才需要)

  1. 左側 Google Auth Platform → 品牌塑造(或第一次會提示 開始)。
  2. 應用程式名稱:填使用者認得的名字,例如公司名稱。
  3. 使用者支援電子郵件:選你的信箱。
  4. 目標對象:選 外部。
  5. 聯絡資訊:填你的信箱 → 同意條款 → 建立。
5.5

建立憑證 → OAuth 用戶端 ID

建立憑證下拉:API 金鑰、OAuth 用戶端 ID、服務帳戶、請幫我選擇

操作

  1. 回 憑證 頁,點 + 建立憑證,選 OAuth 用戶端 ID。

為什麼這樣做

  • API 金鑰 只能代表你的專案,不能讓使用者登入。
  • 服務帳戶 是給程式和程式之間用的,也不是給人登入。
5.6

類型選「網頁應用程式」

應用程式類型下拉:網頁應用程式、Android、Chrome 擴充功能、iOS

操作

  1. 應用程式類型 選 網頁應用程式。

為什麼這樣做

  • 網站在伺服器端完成登入,只有這個類型會給你 Client Secret,也才能填回呼網址。
5.7

填網址

名稱、JavaScript 來源與重新導向 URI 已填

操作

  1. 名稱:tutorial-demo Vercel(只有你看得到)。
  2. 已授權的 JavaScript 來源 → + 新增 URI → https://tutorial-demo.vercel.app(只到網域,結尾不加斜線)。
  3. 已授權的重新導向 URI → + 新增 URI → https://tutorial-demo.vercel.app/api/auth/callback/google。
  4. Use this client for an AI-powered agent 不勾。
  5. 按 建立。彈出視窗會顯示「用戶端 ID」和「用戶端密鑰」。
  6. 用戶端 ID → Vercel 的 AUTH_GOOGLE_ID(Config);用戶端密鑰 → AUTH_GOOGLE_SECRET(Secret)。存好後重新部署。

為什麼這樣做

  • 重新導向 URI 要一字不差:https、網域、路徑都要對,結尾不能多斜線。
  • 路徑 /api/auth/callback/google 是 Auth.js 的預設寫法。用其他登入工具時,請查該工具文件寫的回呼路徑。
5.8

之後要修改

已建立的用戶端:來源與重新導向 URI

操作

  1. 憑證 頁點用戶端名稱就能修改,改完按 儲存。

為什麼這樣做

  • 畫面下方寫著:修改後可能要 5 分鐘到幾小時才生效。剛改完測試失敗,先等幾分鐘再判斷。
5.9

測試使用者:誰可以登入

發布狀態:測試;使用者類型:外部;測試使用者

操作

  1. Google Auth Platform → 目標對象。
  2. 測試使用者 → + Add users,加入每一位要登入後台的人的 Gmail。

為什麼這樣做

  • 「測試」狀態下,只有名單上的帳號能登入,其他人會被 Google 擋下。內部後台正好需要這種白名單,不必送審。
  • 有同事反映登不進去,第一個檢查這裡。上限 100 人。
5.10

(選用)要用 Google 日曆時

Google Calendar API 產品頁,啟用按鈕

操作

  1. API 和服務 → 程式庫,搜尋 Google Calendar API → 啟用。

為什麼這樣做

  • Google 的各項功能預設全部關閉,沒啟用就呼叫會出現 403 錯誤。用不到的不要開。
第 6 章

LINE:收發訊息與 LINE 內表單

LINE Developers 是 LINE 的開發者後台,讓你的網站能收到官方帳號的訊息、回覆客人,以及在 LINE 裡打開你的網頁表單(LIFF)。

本章目標
啟用 Messaging API、接通 Webhook、建立 LIFF 表單
完成後會拿到
LINE_CHANNEL_SECRETLINE_CHANNEL_ACCESS_TOKENLIFF IDChannel ID
預估時間
40 分鐘

免費方案官方帳號免費方案每月主動推播的則數有限;在客人傳訊息後用「回覆」(reply)回應不計入則數,能用回覆就不要用推播。

LINE 這邊要準備兩個東西(LINE 稱為 Channel),而且必須放在同一個 Provider(可以想成「品牌資料夾」)底下:

Channel用途會拿到的值
Messaging API收客人的 LINE 訊息、主動推播通知LINE_CHANNEL_SECRET、LINE_CHANNEL_ACCESS_TOKEN
LINE Login在 LINE 裡開啟你的網頁表單(LIFF),並自動帶入客人身分LIFF ID、Channel ID
6.1

Provider 列表

LINE Developers Providers 列表

操作

  1. 登入 developers.line.biz/console。
  2. 第一次使用:按 Create,名稱填你的品牌名稱。已經有了就點進去。

為什麼這樣做

  • Provider 名稱會出現在客人的授權畫面上,請用客人認得的品牌名,不要用英文代號。
6.2

Provider 裡的 Channel

範例 Provider 下只有一個 LINE Login channel

為什麼這樣做

  • 範例 Provider 裡目前只有 LINE Login,還沒有 Messaging API。這種狀態下表單可以開,但收不到訊息、也無法推播。下面示範怎麼補上。
6.3

建立 Channel

Create a new channel:LINE Login、Messaging API、Blockchain Service、LINE MINI App

操作

  1. 點 Create a new channel → Messaging API。
6.4

Messaging API 要從官方帳號後台開

說明已無法從 LINE Developers 直接建立 Messaging API channel

為什麼這樣做

  • LINE 已經改了流程:Messaging API 不能在這裡直接建,要先有一個 LINE 官方帳號,再到官方帳號後台「啟用 Messaging API」。啟用後,這裡會自動出現對應的 Channel。還沒有官方帳號的人,按 Create a LINE Official Account 先建一個。
6.5

官方帳號後台:找到 Messaging API

LINE Official Account Manager,設定 > Messaging API,狀態未使用

操作

  1. 開 manager.line.biz,點進你的官方帳號。
  2. 右上 設定 → 左側 Messaging API。狀態顯示 未使用。
  3. 按 啟用。

為什麼這樣做

  • 官方帳號就是客人加的那個 LINE 好友。在它身上啟用 Messaging API,客人傳的訊息才會轉給你的網站。
6.6

選 Provider(選了就不能改)

選擇服務提供者:建立服務提供者 或 選擇既有的 Provider

操作

  1. 選你的品牌 Provider(和 LINE Login 同一個)。不要選「建立服務提供者」,除非你還沒有任何 Provider。
  2. 閱讀服務條款後按 同意。
  3. 接著會問隱私權政策與服務條款網址,可以先留空。

為什麼這樣做

  • 這一步送出後無法更改。 選錯的話,就得停用重來,已經累積的客人 ID 對應也會作廢。按下去之前再確認一次。
6.7

啟用後回 LINE Developers 設定

  1. 回 developers.line.biz,你的 Provider 裡會多一個 Messaging API Channel,點進去。
  2. Basic settings 分頁 → Channel secret → 複製 → Vercel 的 LINE_CHANNEL_SECRET(Secret,只勾 Production)。
  3. Messaging API 分頁 → 拉到最下面 Channel access token (long-lived) → Issue → 複製 → LINE_CHANNEL_ACCESS_TOKEN(Secret,只勾 Production)。
  4. Vercel 重新部署。
  5. 回 Messaging API 分頁 → Webhook settings → Webhook URL 填你網站接收 LINE 訊息的網址(例如 https://tutorial-demo.vercel.app/api/line/webhook,以你的程式為準)→ Update。
  6. 打開 Use webhook,按 Verify,出現 Success 才算接通。
  7. 到官方帳號後台 設定 → 回應設定,把 自動回應訊息 關掉。
  8. Basic settings 最下面的 Your user ID 是你自己的 LINE ID,想讓網站推播通知給你時會用到。
6.8

LINE Login Channel 的 Channel ID

LINE Login channel,Basic settings,Channel ID

操作

  1. 還沒有 LINE Login Channel 的話:Create a new channel → LINE Login,App types 勾 Web app。
  2. Basic settings 的 Channel ID 記下來。

為什麼這樣做

  • 你的網站收到 LIFF 傳來的身分證明(ID Token)時,要確認它是發給這個 Channel ID 的,才能確定不是偽造的。
6.9

LIFF:在 LINE 裡開網頁

LIFF 分頁,已有一個 LIFF app

操作

  1. 點進 LINE Login Channel → LIFF 分頁。範例已經有一個表單。

為什麼這樣做

  • 每個 LIFF 都有一個 LIFF ID,你的網頁程式啟動 LIFF 時要用到它,存在 Vercel 環境變數(例如 NEXT_PUBLIC_LIFF_ID)或你網站的設定頁。
6.10

LIFF 網址

LIFF detail:LIFF ID、LIFF URL

為什麼這樣做

  • LIFF URL(https://liff.line.me/...)是要放進 LINE 圖文選單或訊息按鈕的網址。客人點了,會在 LINE 裡打開你設定的網頁。
6.11

常見錯誤:網址過期、少了 openid

Endpoint URL 指向舊網址,Scopes 只有 profile, chat_message.write

操作

  1. Endpoint URL 是 LIFF 實際打開的網頁。網站搬家或改網址後,按 Edit 更新。
  2. Scopes 按 Edit,確認有勾 openid。

為什麼這樣做

  • 這是一個錯誤示範:Endpoint 還指向舊網站,客人點開只會看到錯誤頁。改網址後最容易忘記回來改這裡。
  • Scopes 少了 openid,LIFF 就拿不到身分證明(ID Token),你的網站只能相信網頁自己回報的客人 ID,有心人可以冒充別人下單。
6.12

新增 LIFF

Add a LIFF app:LIFF app name、Size、Endpoint URL

操作

  1. LIFF 分頁按 Add。
6.13

LIFF 設定值

Size Full,Endpoint URL,Scopes openid profile,Add friend option On (Normal)

操作

  1. LIFF app name:例如 預約表單。
  2. Size:Full。
  3. Endpoint URL:你網站表單頁的完整網址(要先做好這個頁面)。
  4. Scopes:勾 openid、profile。chat_message.write 只有在「表單送出後要以客人身分在聊天室留一句話」時才勾。
  5. Add friend option:On (Normal)。
  6. Scan QR、Module mode 保持關閉。按 Add。

為什麼這樣做

  • Full 是全螢幕,欄位多的表單客人不用在小視窗裡捲。
  • openid 讓網站能驗證客人身分;profile 拿到名字和大頭貼,你在後台才認得出是誰。
  • chat_message.write 打開後視窗不能縮小,沒需要就別勾。
  • 加好友選項打開,客人填表時會被提示加你的官方帳號。沒加好友的人,之後無法推播報價或提醒給他。
6.14

把 LINE Login 連到官方帳號

Basic settings 下方 Linked LINE Official Account 顯示 –(未連結)

操作

  1. LINE Login Channel → Basic settings 最下方 → Linked LINE Official Account → Edit → 選你的官方帳號。

為什麼這樣做

  • 範例顯示 –(未連結),這時上一步的加好友提示不會出現。要先完成「啟用 Messaging API 並選同一個 Provider」,這裡的下拉選單才選得到官方帳號。
第 7 章

Dify:接上 AI

Dify 讓你不用寫程式,用拖拉方塊的方式組出 AI 流程,例如把客人的一段話整理成訂單資料。

本章目標
建立 AI 工作流、讓網站和 Dify 互相呼叫
完成後會拿到
Dify API Key(每個應用一把)你網站發給 Dify 的 Token
預估時間
40 分鐘

免費方案免費的 Sandbox 方案有訊息額度(左上角顯示剩餘點數)與應用數量上限,以 Dify 定價頁為準。

Dify 和你的網站之間是雙向的,兩個方向各用一把不同的鑰匙:

方向例子鑰匙存在哪裡
網站 → Dify網站把客人的 LINE 訊息送給 AI 整理Dify 應用的 API KeyVercel 環境變數(例如 DIFY_API_KEY)
Dify → 網站AI 整理完,呼叫網站建立訂單你的網站發給 Dify 的 TokenDify 的工具設定裡
7.1

建立應用

Dify 工作室,建立下拉:建立空白應用、從應用模版建立、匯入 DSL 檔案

操作

  1. cloud.dify.ai → 工作室 → 建立 → 建立空白應用。

為什麼這樣做

  • 匯入 DSL 檔案 可以載入別人做好的流程。新手建議先從空白開始,才看得懂每一個步驟在做什麼。
7.2

類型選工作流

建立空白應用:工作流、聊天流

操作

  1. 選擇 App Type 選 工作流(預設是聊天流,要記得改)。

為什麼這樣做

  • 「把一段文字整理成資料」這種一問一答的工作,用工作流。網站呼叫的網址是 /workflows/run。
  • 要記得上下文、多輪對話的客服,用聊天流。網站呼叫的網址是 /chat-messages。
  • 兩種的呼叫網址不同,選錯類型,網站那邊就會呼叫失敗。
7.3

名稱與描述

工作流已選,應用名稱與描述已填

操作

  1. 應用名稱:寫清楚用途,例如 LINE 訊息整理。
  2. 描述:寫輸入什麼、輸出什麼,例如「輸入 text;輸出日期、人數、上下車地點」。
  3. 按 建立,接著在畫布上設計流程。

為什麼這樣做

  • 開始節點的輸入變數名稱,必須和你網站程式送過來的欄位名稱一致,否則資料送不進去。寫在描述裡,日後調整時不會忘。
7.4

存取點:取得 API 網址

存取點頁面:Web 應用程式、後端服務 API、MCP 伺服器

操作

  1. 應用左側 存取點。
  2. 後端服務 API 確認為 服務中,API Endpoint 是 https://api.dify.ai/v1。
  3. Web 應用程式:不打算讓別人直接使用這個 AI 頁面,就把開關關掉。

為什麼這樣做

  • API Endpoint 就是你網站要呼叫的 Dify 網址。用 Dify 雲端版都是這個;自己架設 Dify 才會不同。
  • Web 應用程式 開著的話,任何人拿到網址都能直接用,消耗你的額度。
  • MCP 伺服器 是把這個 AI 流程提供給 Claude 等 AI 助理使用,跟本章無關,保持停用。
7.5

API 金鑰:每個應用一把

API 金鑰對話框,建立金鑰按鈕

操作

  1. 按 API 金鑰 → + 建立金鑰 → 複製。
  2. 存成 Vercel 環境變數(Secret,只勾 Production),名稱依你的程式而定。有好幾個應用就各存一個,例如 DIFY_KEY_LINE_PARSE、DIFY_KEY_FAQ。
  3. 重新部署。

為什麼這樣做

  • Dify 的金鑰是一個應用一把,不是整個帳號一把。五個應用就有五把。
  • 畫面上的提醒:金鑰不能寫在網頁前端的程式碼裡,只能放在伺服器端(也就是 Vercel 環境變數)。
7.6

你的網站要能發 Token 給別人

反方向(Dify 呼叫你的網站)需要你的網站自己發 Token。網站的管理頁應該要有一個「建立 Token」的表單,至少包含這些欄位:

欄位用途給 Dify 的建議值
名稱看得出這把 Token 給誰用Dify
權限範圍(scope)限制這把 Token 能做哪些事只勾讀取訂單、建立訂單、產生報價草稿
有效天數到期自動失效90 天
每分鐘上限防止被大量呼叫60 次
IP 白名單只允許特定來源Dify 雲端版的 IP 不固定,留空
撤銷出事時立刻停用清單上每一把都要有停用按鈕
  • 不要給 Dify:送出報價給客人、派車、刪除資料等權限。
  • Token 建立後通常只顯示一次,馬上複製到 Dify。
7.7

把網站 API 變成 Dify 的工具

集成 > 工具:Tool Plugin、MCP、工作流程作為工具、Swagger API 作為工具

操作

  1. 左側 集成 → 工具 → Swagger API 作為工具 → 建立 Swagger API 作為工具。

為什麼這樣做

  • 把你網站的 API 包成 Dify 工具後,每個流程都能直接呼叫「查訂單」「建訂單」,不用每次重新設定網址和鑰匙。
7.8

工具名稱

建立自定義工具:名稱、Schema、可用工具、鑑權方法

操作

  1. 名稱:tutorial_demo(英文小寫、底線)。

為什麼這樣做

  • 工具名稱會出現在 AI 的指令和紀錄裡,用英文比較穩定。
7.9

匯入 API 說明書(OpenAPI)

Schema 已填,可用工具解析出 createOrder、getOrder

操作

  1. 你的網站有提供 OpenAPI 規格網址(例如 https://tutorial-demo.vercel.app/api/v1/openapi.json):按 + 從 URL 中匯入 貼上。
  2. 沒有的話,把 OpenAPI 內容貼進 Schema 欄位(畫面中是精簡範例)。
  3. 下方 可用工具 會列出解析到的功能,右側 測試 可以先試。

為什麼這樣做

  • OpenAPI 是一份標準格式的「API 說明書」,Dify 讀了就知道有哪些功能、要帶哪些資料。
  • 用網址匯入,網站改版後重新匯入就能同步,不會手動貼的跟實際不一樣。
  • 每個功能的說明要寫清楚,AI 是靠這些文字判斷該用哪一個。
7.10

鑑權方法:預設值是錯的

鑑權方法對話框,選了標題後,頭部字首預設 Basic

操作

  1. 鑑權方法 右側齒輪 → 鑑權型別 選 標題。

為什麼這樣做

  • 選了「標題」之後,下面的 鑑權頭部字首 預設是 Basic。大多數網站 API 用的是 Bearer,保留 Basic 會一直得到 401(未授權)錯誤。
7.11

改成 Bearer

鑑權頭部字首 Bearer,鍵 Authorization,值 輸入 API Key

操作

  1. 鑑權頭部字首 改選 Bearer。
  2. 鍵 保持 Authorization。
  3. 值 貼上你網站發給 Dify 的 Token(畫面中是示範值)。只貼 Token 本身,前面不要自己加 Bearer。
  4. 按 儲存,再按工具表單的 儲存。

為什麼這樣做

  • Dify 會自動在前面加上 Bearer 。值裡再寫一次就會變成 Bearer Bearer xxx,一樣得到 401。
7.12

另一種接法:MCP

集成 > 工具 > MCP,新增 MCP 伺服器 (HTTP)

操作

  1. 你的網站如果有提供 MCP 網址,可以改用這種方式:集成 → 工具 → MCP → 新增 MCP 伺服器 (HTTP)。

為什麼這樣做

  • MCP 會自動列出網站提供的所有功能和說明,不用另外維護 OpenAPI 說明書。和上面的 Swagger 工具二選一就好,同一個功能不要接兩次。
7.13

MCP 表單

新增 MCP 伺服器 (HTTP):伺服器 URL、名稱、識別碼、身份驗證

為什麼這樣做

  • 身份驗證 分頁預設是 OAuth(動態客戶端註冊)。用固定 Token 的網站要把它關掉,改在 標題 分頁設定。
7.14

填網址、關閉動態註冊

伺服器 URL、名稱、識別碼已填,動態客戶端註冊關閉

操作

  1. 伺服器 URL:你網站的 MCP 網址,例如 https://tutorial-demo.vercel.app/api/mcp。
  2. 名稱與圖示:例如 我的後台。圖示會自動抓網站的 favicon。
  3. 伺服器識別碼:tutorial-demo(建立後不能改)。
  4. 使用動態客戶端註冊 關閉,下方兩欄留空。

為什麼這樣做

  • 識別碼是流程內部用來指這個 MCP 的代號,之後改不了,用和專案一樣的名稱最不容易搞混。
7.15

在「標題」分頁加上 Token

標題分頁:Authorization = Bearer <Token>

操作

  1. 切到 標題 分頁 → + 新增標題。
  2. 標題名稱:Authorization。
  3. 標題值:Bearer 加上 Token(這裡要自己寫 Bearer 和一個空格;畫面中是示範值)。
  4. 按 新增並授權。

為什麼這樣做

  • 這是最容易混淆的地方:MCP 的標題會原封不動送出,不會自動加 Bearer;上面 Swagger 工具則會自動加。兩邊的寫法剛好相反。
7.16

不建工具,直接在流程裡打 API

只有一個流程要用時,可以在工作流畫布上加一個 HTTP 請求 節點:

  • 方法 POST,網址填你網站的 API,例如 https://tutorial-demo.vercel.app/api/v1/orders。
  • 鑑權 → API-Key → 類型 Bearer → 貼 Token。
  • Headers 加一筆 Idempotency-Key,值填 {{sys.workflow_run_id}}(你的網站要支援這個功能)。
  • Body 選 JSON,欄位引用前面 AI 節點整理出來的變數。
第 8 章

n8n:定時自動執行

n8n 是自動化工具,在指定時間或事件發生時,自動呼叫你的網站做事。

本章目標
建立定時排程,讓 n8n 安全地呼叫網站
完成後會拿到
CRON_SECRET
預估時間
20 分鐘

免費方案n8n 雲端版需付費(有試用期);自己架設免費,但要自己維護主機。

n8n 負責「時間」相關的工作,例如每天早上寄簡報、每 15 分鐘檢查有沒有逾期未處理的訂單。做法是:n8n 在指定時間,呼叫你網站上的一個網址。

你的網站要提供:一個專門給排程呼叫的網址(例如 POST /api/cron/daily-briefing),而且要檢查請求裡有沒有帶正確的密碼,否則任何人都能觸發。

  1. 產生一組密碼(方法見「環境變數總表」章),存成 Vercel 的 CRON_SECRET(Secret),重新部署。
  2. n8n 左側 Credentials → Add credential → 搜尋 Header Auth:Name 填 Authorization,Value 填 Bearer 加上剛才的密碼 → 儲存。
  3. 新增工作流:加 Schedule Trigger 節點,設定執行時間(例如每天 07:30)。
  4. 接一個 HTTP Request 節點:Method 選 POST,URL 填你網站的排程網址,Authentication 選 Generic Credential Type → Header Auth → 選剛建的 Credential。
  5. 工作流右上 ⋯ → Settings → Timezone 改為 Asia/Taipei。
  6. 按 Test workflow 試一次,網站回應成功後,打開右上角 Active。

進階:延時執行(例如報價 72 小時後沒回覆就自動提醒):網站在建立報價時通知 n8n 的 Webhook 節點 → n8n 用 Wait 節點等到指定時間 → 再呼叫網站的回呼網址。回呼時要帶網站事先產生的簽章,網站確認簽章無誤才執行,避免被別人亂觸發。

第 9 章

MCP:讓 AI 助理幫你管系統

本章目標
讓 Claude 能管理部署、操作你的網站
完成後會拿到
給 Claude 的 Token
預估時間
15 分鐘

MCP 讓 Claude 這類 AI 助理可以直接操作其他系統。分成兩種用途:

用途連到哪裡可以做什麼怎麼登入
管理部署Vercel、Neon、GitHub 官方提供的 MCP請 AI 查部署錯誤、看資料表、改程式OAuth 登入(推薦)
操作業務資料你自己網站提供的 MCP(例如 /api/mcp)請 AI 查訂單、建立訂單你網站發的 Token

在 claude.ai 加入:左下角頭像 → 設定 → 連接器 → 新增自訂連接器,貼上網址。官方 MCP 會跳出登入畫面,登入同意即可。

在 Claude Code 加入(終端機執行):

claude mcp add --transport http vercel https://mcp.vercel.com
claude mcp add --transport http neon https://mcp.neon.tech/mcp
claude mcp add --transport http github https://api.githubcopilot.com/mcp/

# 你自己網站的 MCP(Token 換成你網站發給 Claude 的那一把)
claude mcp add --transport http tutorial-demo https://tutorial-demo.vercel.app/api/mcp \
  --header "Authorization: Bearer <你的 Token>"

加完後在 Claude Code 輸入 /mcp,看到狀態為已連線即可。

  • Neon 登入時會問要給「單一專案」還是「所有專案」,選單一專案。
  • 給 Claude 的 Token 和給 Dify 的分開發,名稱寫 Claude,權限依你要它做的事勾選。
  • 會刪除資料的功能,網站應該要求二次確認,AI 不能一步就刪掉。

接通之前先測試

一、先用 curl 確認 API 和 Token 正常(Mac 用「終端機」、Windows 用 PowerShell,Windows 請把 curl 寫成 curl.exe):

curl -i https://tutorial-demo.vercel.app/api/v1/orders \
  -H "Authorization: Bearer <你的 Token>"
  • 第一行出現 HTTP/2 200:Token 正確,API 正常。
  • 401:Token 錯了或過期;403:Token 對,但沒有讀取訂單的權限。
  • -i 的意思是把狀態碼一起印出來,排錯時一定要加。

二、用 MCP Inspector 看你的 MCP 有哪些工具(官方的測試工具,需要 Node.js):

npx @modelcontextprotocol/inspector
  1. 瀏覽器會自動開啟 Inspector 頁面。
  2. Transport Type 選 Streamable HTTP,URL 填 https://tutorial-demo.vercel.app/api/mcp。
  3. 在 Header 欄位加 Authorization,值為 Bearer <你的 Token>,按 Connect。
  4. 切到 Tools 分頁,按 List Tools,看到工具清單就代表 MCP 正常。可以點一個唯讀工具(例如查訂單)實際執行一次。
第 10 章

環境變數總表與密碼產生方法

本章目標
一張表對照所有鑰匙
預估時間
查閱用

下表是這套架構常見的環境變數。實際名稱以你的程式為準,大小寫必須完全一致。

變數從哪裡拿套用環境類型
DATABASE_URLNeon Connect(Pooling 開)Production、Preview 各一組Secret
DATABASE_URL_UNPOOLEDNeon Connect(Pooling 關)Production、Preview 各一組Secret
AUTH_SECRET自己產生Production、Preview 用不同值Secret
AUTH_GOOGLE_IDGoogle Cloud 憑證Production(Preview 要有固定網址才加)Config
AUTH_GOOGLE_SECRETGoogle Cloud 憑證同上Secret
APP_BASE_URL你的正式網址ProductionConfig
BLOB_READ_WRITE_TOKENVercel Blob 自動建立全部Secret
LINE_CHANNEL_SECRETLINE Messaging API › Basic settingsProductionSecret
LINE_CHANNEL_ACCESS_TOKENLINE Messaging API › Long-lived tokenProductionSecret
NEXT_PUBLIC_LIFF_IDLINE Login › LIFFProductionConfig
DIFY_API_KEY(每個應用一個)Dify › 存取點 › API 金鑰ProductionSecret
CRON_SECRET自己產生Production、PreviewSecret

誰拿著哪一把鑰匙:

誰呼叫誰用哪一把存在哪裡
網站 → Neon連線字串Vercel DATABASE_URL
網站 → DifyDify API KeyVercel 環境變數
Dify → 網站網站發的 TokenDify 工具設定
LINE → 網站(網站用 Channel secret 檢查)Vercel LINE_CHANNEL_SECRET
網站 → LINEChannel access tokenVercel LINE_CHANNEL_ACCESS_TOKEN
n8n → 網站CRON_SECRETn8n Credential
Claude → 網站網站發的 TokenClaude 連接器設定
Claude → Vercel/Neon/GitHubOAuth 登入不用手動貼

怎麼產生一組安全的亂碼密碼(AUTH_SECRET、CRON_SECRET 這類「自己產生」的值):

Mac、Linux、Windows 都可用(需先安裝 Node.js):

node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

Mac、Linux 也可以用:

openssl rand -hex 32
第 11 章

完成後的驗收清單

本章目標
逐項確認每一段都接通
預估時間
20 分鐘
  1. 打開 https://tutorial-demo.vercel.app,網站正常顯示。
  2. 用 Google 登入成功;用不在測試使用者名單上的帳號登入,會被擋下。
  3. 在測試站(Preview)新增一筆資料,到 Neon 的正式分支查不到它。
  4. LINE Developers 的 Webhook Verify 顯示 Success;用自己的手機傳一句話給官方帳號,網站有收到。
  5. 在 LINE 裡點 LIFF 網址,表單打開、送出後網站有資料,客人名字正確。
  6. 在 Dify 工具按 測試:Token 正確時成功;故意改錯一個字,會得到 401。
  7. n8n 手動執行一次排程,網站回應成功;把 Credential 拿掉再執行,會得到 401。
  8. Claude Code 輸入 /mcp,看到你的網站已連線。
  9. 上傳一個檔案,用無痕視窗直接打開檔案網址:Private Blob 應該打不開。
第 12 章

常見錯誤排除

本章目標
出錯時對照症狀找原因
預估時間
查閱用
看到的狀況最可能的原因怎麼處理
改了環境變數,網站沒反應沒有重新部署Deployments → 最新一筆 ⋯ → Redeploy
Google 登入出現 redirect_uri_mismatch重新導向 URI 和實際網址不一樣(多了斜線、http/https、網域不同)回 Google Cloud 憑證頁逐字核對;改完等幾分鐘
Google 登入出現「存取遭封鎖」帳號不在測試使用者名單Google Auth Platform → 目標對象 → 加入該帳號
測試站(Preview)無法 Google 登入測試站網址沒登記給測試站綁固定網址並登記(Vercel、Google 兩章)
測試站突然全部連不上資料庫Neon preview 分支被自動刪除重建分支並設 Auto-delete: Never,更新 Vercel 的 Preview 連線字串
早上第一次開網站特別慢Neon 資料庫休眠中正常現象,第二次就快了
網站整體很慢網站、資料庫不在同一區Vercel 函式與 Neon 都改到新加坡
建立資料表時出現怪錯誤migration 用了 pooled 連線migration 改用 DATABASE_URL_UNPOOLED
第一次 git push 被拒絕(rejected)GitHub 上建 repo 時多加了 README 或 .gitignore建一個全空的 repo 重推,或先 git pull --rebase origin main 再推
LINE Webhook Verify 失敗金鑰沒設好、沒重新部署,或值多了換行重貼 LINE_CHANNEL_SECRET、重新部署,再按 Verify
客人訊息同時收到兩則回覆官方帳號的自動回應沒關官方帳號後台 設定 → 回應設定 → 關閉自動回應
LIFF 拿不到客人身分Scopes 沒勾 openidLIFF 設定 → Scopes → 加勾 openid
Dify 呼叫網站一直 401鑑權選了 Basic,或值裡多寫了 BearerSwagger 工具改 Bearer、值只貼 Token;MCP 標題值要自己加 Bearer
Dify 建了重複的訂單節點重試時沒有防重複機制HTTP 請求加 Idempotency-Key
n8n 排程時間差 8 小時工作流時區是 UTC工作流 Settings → Timezone → Asia/Taipei
Vercel 頁面上改了區域沒效果被 vercel.json 覆寫改 vercel.json 裡的 regions