這份手冊假設你從零開始——沒寫過程式、沒用過終端機也沒關係。它會帶你一步步把電腦準備好、建立三個平台帳號、完成 Claude Code 登入,理解 AI 開發到底怎麼運作,接著用一條固定的 Git 流程把作品自動部署到 Vercel 或 Cloudflare。讀完你會擁有一套可以每天重複的工作流:在自己電腦上開發,推送一次,網站自動上線。
部署看起來複雜,是因為三件事被混在一起談。把它們拆開,整套流程就只有一個方向。第一件事是地端開發:你的電腦,Claude Code 在這裡讀寫檔案、跑測試、執行指令。第二件事是版本控制:GitHub,所有程式碼的唯一真實來源(single source of truth),記錄每一次變更與誰改了什麼。第三件事是部署:Vercel 與 Cloudflare,它們不保管你的程式碼,而是「訂閱」你的 GitHub 倉庫,每當有新的推送就自動把最新版本建置成一個可公開存取的網站。
關鍵在於:你幾乎不會手動把檔案上傳到 Vercel 或 Cloudflare。你只做一件事——git push。推送到 GitHub 之後,Vercel 和 Cloudflare 會收到通知,自己去拉取程式碼、安裝相依套件、執行建置、產生網址。這叫做 Git 驅動的部署(Git-based deployment)。它的好處是:每一次線上的版本,都能對應到 GitHub 上一個確切的 commit;要回滾,就是回到上一個 commit。
每次推送會分流成兩種環境。推到功能分支或開 Pull Request,平台會建一個預覽環境(preview),一個獨立網址,讓你在合併前先檢查。等 PR 合併進 main 主分支,平台才會更新生產環境(production)。預覽與生產用的是同一份建置流程,所以「在預覽看起來對」基本上等於「上線也會對」。
這份手冊會重複用到一組詞。你不用背,先看過一遍,讀到時知道它在講什麼即可。它們大致對應設計工作裡你已經熟悉的概念。
| 術語 | 白話解釋 | 設計類比 |
|---|---|---|
| 終端機 / Terminal | 用打字下指令操作電腦的黑色視窗,取代滑鼠點選。 | 像沒有按鈕的 Figma,改用指令操作 |
| CLI | 命令列工具。在終端機裡輸入的指令程式,例如 git、vercel。 |
各家 App 的「快捷鍵版本」 |
| Repository / Repo | 一個專案的程式碼資料夾,含完整修改歷史。 | 一個 Figma 專案檔 |
| Commit | 把當下的變更存成一個有說明的快照。 | Figma 的具名版本 / version history |
| Branch / 分支 | 從主線複製出來獨立修改的副本,不影響正式版。 | 複製一個 frame 改改看,不動原稿 |
| Push / 推送 | 把本機的 commit 上傳到 GitHub。 | 把本機檔案同步上雲端 |
| Pull Request / PR | 提出「請把我的分支合併進主線」的審查請求。 | 送出設計稿請人 review 後再 merge |
| Build / 建置 | 把原始碼編譯成瀏覽器能跑的最終網站檔案。 | 把工作檔 export 成正式輸出 |
| Deploy / 部署 | 把建置好的網站放到公開網址上,讓任何人能開。 | 把作品發佈成公開連結 |
| 環境變數 | 不寫進程式碼、另外保管的設定值(多為密鑰)。 | 不該外流的密碼,單獨鎖起來 |
這一節是一次性設定,做完之後日常開發都不用再碰。預估約 30 到 40 分鐘。以下以 macOS 為例(Tenten 設計師多用 Mac);Windows 大原則相同,建議改用 WSL2 取得近似的環境。照順序做,每一步做完再進下一步。
終端機是後面所有指令的舞台。在 Mac 上按 Cmd + 空白鍵 開啟 Spotlight,輸入「Terminal」按 Enter,就會出現一個可以打字的視窗。看到一行以 $ 或 % 結尾的提示符號就代表它在等你下指令。本手冊的指令,複製貼上後按 Enter 即可執行。
Homebrew 是 Mac 上安裝開發工具的標準方式,之後用一行 brew install 就能裝好各種工具。把下面這行貼進終端機執行,過程會請你輸入電腦密碼(輸入時不會顯示字元,是正常的)。
Node.js 是執行前端工具與 CLI 的引擎(npm 也隨它一起裝好);Git 是版本控制工具。用 Homebrew 一次裝齊,再用 -v / --version 確認。看到版本號就代表成功。
VS Code 是免費的程式碼編輯器,用來開啟、檢視專案檔案,也是 Claude Code 的好搭檔。到 code.visualstudio.com 下載安裝。Claude Code 在 VS Code 內有官方擴充套件,能在編輯器裡直接看到它修改了哪些檔案、哪幾行——對習慣看視覺差異的設計師特別友善。
工具就緒後,註冊這四個帳號。建議都用同一個公司 email,並且 Vercel 與 Cloudflare 都選「用 GitHub 帳號登入」,日後連結倉庫最省事。
| 帳號 | 註冊網址 | 用途 |
|---|---|---|
| Claude | claude.ai | Claude Code 的訂閱帳號(Pro / Max),用來驗證登入 |
| GitHub | github.com | 保管程式碼與歷史,是雲端部署的來源 |
| Vercel | vercel.com | 部署平台 A;註冊時選「Continue with GitHub」 |
| Cloudflare | dash.cloudflare.com | 部署平台 B(Pages / Workers) |
最後裝齊三個會天天用到的 CLI:Claude Code 本身、Vercel 的 vercel、Cloudflare 的 wrangler。用 npm install -g 做全域安裝(-g 代表整台電腦都能用)。
PATH 設定貼進去再重開一次。安裝階段的卡關大多是這個原因,別緊張。
工具裝好了,還要讓它們知道「你是誰」。這節把 Claude Code 與三個平台的登入一次做完。全部走瀏覽器授權(OAuth),不需要手動複製貼上任何金鑰。
進到任一資料夾,輸入 claude 啟動。第一次會引導你登入,先選驗證方式。模式 A 是 Claude 訂閱帳號(Pro / Max):走 OAuth,Claude Code 會開瀏覽器到 claude.ai,你按授權就自動帶回憑證,用量算在訂閱方案裡——多數同事用這個。模式 B 是 Anthropic Console API Key:用 API 按量計費,把金鑰設成環境變數 ANTHROPIC_API_KEY。登入後憑證存在本機(macOS 存於系統 Keychain),之後不用重登。
程式碼要推上 GitHub、雲端要連到 GitHub,所以這三個帳號也要在終端機登入。GitHub 用官方 gh CLI(用 Homebrew 裝),其餘各跑一次 login。同樣都是開瀏覽器授權。
claude setup-token 產生長效 token,存成環境變數 CLAUDE_CODE_OAUTH_TOKEN;或改用 ANTHROPIC_API_KEY。這類密鑰一律放進 GitHub / Vercel / Cloudflare 的 Secrets 設定,絕不寫進程式碼或 commit。
和網頁版聊天最大的差別:Claude Code 跑在你的終端機裡,能直接讀寫專案檔案、執行指令、跑測試。你不必把程式碼複製來貼去——你描述要什麼,它實際動手改你的專案。把它想成一位坐在你旁邊、會打字的工程師:你給方向、做決定、驗收成果,鍵盤的事交給它。
先用 cd 進到你的專案資料夾,輸入 claude 啟動,然後直接用中文描述你要做的事。具體一點會更準——與其說「做個表單」,不如說「在聯絡頁加一個含姓名、email、訊息三欄的表單,送出後顯示成功訊息」。
Claude Code 有三種運作模式,按 Shift + Tab 循環切換,畫面下方會顯示目前模式。對設計師來說,剛開始建議多用「規劃模式」:先讓它把計畫講清楚、你看過再動手,最安全。
| 模式 | 它會怎麼做 | 什麼時候用 |
|---|---|---|
| 一般模式 | 每次要改檔案或跑指令前,先問你同意 | 預設;邊做邊確認 |
| 規劃模式 Plan | 只研究與提計畫,先不動任何檔案 | 複雜需求;先對齊方向再執行 |
| 自動接受編輯 | 不再逐次詢問,自動套用編輯 | 你已信任這輪任務、想加速時 |
在 Claude 對話中以斜線 / 開頭的是內建指令。記住下面這幾個就夠日常使用。另外,打 @ 可以指定某個檔案帶進對話,按 Esc 可中斷它正在做的事。
/init 會在專案根目錄產生一個 CLAUDE.md。它是給 Claude 看的專案說明:用什麼框架、檔案放哪、命名慣例、團隊規則。每次啟動 Claude Code 都會自動讀它,所以把「這個專案的固定規矩」寫進去,就不必每次重講。它本身也是程式碼的一部分,會跟著 commit 進 Git,團隊共享同一份。
Claude 要改檔案或執行指令前,(在一般模式下)會先列出它打算做什麼、停下來等你按同意。養成看過再放行的習慣:改檔案時看它改了哪幾行,執行指令時看清楚那行指令在做什麼。改完後一定到瀏覽器用 npm run dev 親眼確認效果,不要只看它說「完成了」。
要看懂部署,先看懂每個平台的職責。GitHub 是版本控制與協作中心,保管程式碼與完整歷史。Vercel 與 Cloudflare 是部署平台,連到你的 GitHub 倉庫,自動把程式碼變成線上服務——兩者定位接近,差別在執行環境與生態。下面把每個平台的核心概念拆成卡片,記住卡片左上角的分組,就知道哪個指令屬於哪個平台。
兩者都能部署現代前端與全端應用,且都支援 Git 自動部署。下表是選型時的主要差異點,不是優劣排名——多數團隊會依框架、後端需求與既有生態決定,有時兩者並用。
| 面向 | Vercel | Cloudflare |
|---|---|---|
| 最順的框架 | Next.js(原生最佳) | 多框架;Next.js 需 OpenNext 轉接 |
| 後端執行 | Functions · Fluid Compute(完整 Node.js) | Workers(邊緣執行,就近低延遲) |
| 內建資料 / 儲存 | 透過 Marketplace 整合 | D1 · R2 · KV · Durable Objects 原生 |
| 命令列工具 | vercel |
wrangler |
| 適合場景 | Next.js 為主的產品、需要完整 Node 後端 | 邊緣優先、用到 Cloudflare 儲存與網路生態 |
前面是工具與觀念,這節第一次把它們串起來:建立一個真的專案,接上 GitHub,再連到 Vercel。這套「連結」每個新專案只做一次,做完之後,日常就只剩下一節要講的每日流程。我們用 Next.js 當範例,它是 Tenten 常用、且 Vercel 原生支援的框架。
進到你放專案的資料夾,執行下面這行。它會問幾個問題(專案名稱、要不要 TypeScript、Tailwind 等),不確定就一路按 Enter 用預設值。建好後它已自動幫你做了 Git 初始化與第一個 commit。
部署之前,先在自己電腦上確認它能跑。npm run dev 會啟動本機伺服器,終端機會印出一個 http://localhost:3000 網址,用瀏覽器打開就能看到預設首頁。這時你可以啟動 claude 開始改它。要停掉伺服器按 Ctrl + C。
把這個專案上傳到 GitHub,成為雲端部署的來源。因為 create-next-app 已經初始化 Git,這裡直接用 gh 建立遠端倉庫並推送。--private 代表私有倉庫。
這是把 GitHub 與雲端「綁定」的關鍵一步,只需做一次。打開 vercel.com/new,選擇剛剛建立的 GitHub 倉庫按 Import。Vercel 會自動辨識這是 Next.js 專案、自動填好建置設定,你按 Deploy 即可。幾分鐘後它給你一個正式網址。從這一刻起,這個倉庫每次 push 都會自動部署——你之後不必再回 Vercel 操作。
到這裡,你已經有一個「地端能開發、push 就自動上線」的專案。剩下的,就是把這個循環變成每天的習慣。
把前面的觀念落成每日操作。下面十張卡片是一個功能從開始到上線的標準順序——前六步是固定流程,後四步是讓流程更穩的實務習慣。第一次設定好專案與 Git 連結後,日常其實只在重複步驟 02 到 06。
從最新的 main 拉一個功能分支:git switch -c feat/login-page。main 永遠保持可部署狀態,所有開發都在分支上進行,改壞了也不影響線上。
在專案資料夾啟動 claude,描述你要的功能讓它讀寫檔案、跑測試。改完用 npm run dev 在本機預覽,確認畫面與行為正確再進下一步。
git add -p 挑要進的變更,git commit -m 寫一句說明「做了什麼」。一個 commit 對應一件事,日後回滾與審查都更精準。
git push -u origin feat/login-page 後 gh pr create。推送的瞬間,Vercel / Cloudflare 會自動建一個 Preview 網址,貼在 PR 裡讓你和同事審。
不要只看本機。打開 PR 裡的 Preview 連結,那是用正式建置流程跑出來的環境,最接近上線結果。CI 的測試也會在這時跑完並回報通過與否。
Preview 等於上線預演審查通過後 Squash and merge。合併進 main 會觸發 Production 部署,幾分鐘後正式網址就是最新版本。你全程沒有手動上傳任何檔案。
merge main = 上線API 金鑰、資料庫連線字串設在 Vercel / Cloudflare 的環境變數,本機用 vercel env pull 同步。.env 一律加進 .gitignore,密鑰永不進倉庫。
平台可為 Preview 與 Production 設不同變數值。把測試資料庫綁 Preview、正式資料庫綁 Production,預覽環境就不會誤動到線上資料。
環境隔離,避免誤傷線上壞了不必急著修 code。Vercel / Cloudflare 儀表板都能一鍵 Rollback 回上一個正常部署,因為每個版本都對應一個 commit。先止血,再排查。
回滾優先於除錯Claude Code 能直接執行 git、gh、vercel、wrangler。你可以請它「開分支、提交、推送並開 PR」,它會逐步執行——但合併與上生產這類動作,讓它先問過你再做。
以下是一段示意操作:在一個已連到 Vercel 的 Next.js 專案裡,用 Claude Code 新增一個聯絡頁,開分支、提交、推送、取得 Preview 網址、合併上線。重點不在指令本身,而在每一步分別發生在地端、GitHub、還是雲端。Cloudflare 的流程結構相同,只是把 vercel 換成 wrangler。
第一,觸發部署的是 git push,不是任何上傳動作。Vercel 與 Cloudflare 事先連到了這個 GitHub 倉庫,推送一發生就自動拉取、建置、上線。你的職責止於 push。
第二,Preview 與 Production 是兩個自動分流的環境。分支 / PR 進 Preview,合併進 main 才上 Production。所以你永遠有一個合併前就能點開檢查的真實網址。
第三,Claude Code 可以代跑 Git 與部署指令,但邊界要清楚。讓它處理 add / commit / push / 開 PR 很安全;合併與上生產這類不可逆動作,讓它停下來等你確認再執行。
卡關是學習的常態,不是你做錯了什麼。下表是初學者最常撞到的狀況、原因與解法。遇到紅字錯誤先別慌——絕大多數都在這張表裡,而且都救得回來。
| 你看到的狀況 | 多半是因為 | 怎麼解 |
|---|---|---|
command not found: claude |
終端機還沒載入剛裝的工具 | 關掉終端機重開一個;仍不行就補上 Homebrew 提示的 PATH 設定 |
npm install -g 出現 EACCES 權限錯誤 |
Node 裝在系統保護目錄 | 用 brew install node 重裝(避免動到系統),別習慣性加 sudo |
Vercel 建置失敗 Module not found |
相依沒列進 package.json,或 lock 檔沒提交 | 本機 npm install <套件> 後,把 package.json 與 lock 檔一起 commit、push |
| 改了東西,線上卻沒變 | 忘了 push,或推到了別的分支 | git status 確認已提交,git push 推到對的分支(生產通常是 main) |
頁面壞掉,變數讀到 undefined |
環境變數沒設在平台,或設了沒重新部署 | 在 Vercel / Cloudflare 設好變數後,觸發一次 Redeploy 才會生效 |
push 被拒 non-fast-forward |
遠端有你本機還沒有的 commit | 先 git pull --rebase 接回遠端變更,再 push |
| Claude 改壞了,想還原 | 這次修改還沒 commit | 未提交的用 git restore <檔案> 丟棄;已 commit 的用平台 Rollback 回上一版 |
不小心把 .env 提交進去了 |
密鑰外洩風險 | 立即在平台輪換(重新產生)那把金鑰,並把 .env 加進 .gitignore |
.env 與 .env.local 寫進 .gitignore,密鑰只放在平台的環境變數設定。
package.json 列出的相依套件、且只有平台環境變數裡有的值。漏記相依、漏設變數,本機正常但雲端建置會失敗。以 Preview 的建置結果為準。
git push --force、刪檔、合併、刪 branch 這類不可逆動作。高風險指令先讓它說明再核准,別一路放行。
當基本的「push 即部署」已經順手,下面幾項能讓團隊協作更穩、設定更可控。不用一次全做,挑當下會痛的先做。
1. 綁自訂網域。在 Vercel 或 Cloudflare 的專案設定加上你的網域(例如 app.tenten.co),依指示設定 DNS。之後 Production 就走自己的網址,而非平台預設子網域。
2. 把設定寫進版控的設定檔。Vercel 用 vercel.ts(以 TypeScript 宣告 build 指令、rewrites、headers、cron),Cloudflare 用 wrangler.jsonc(宣告路由、相容性日期、資源繫結)。設定進 Git,團隊才有一致來源。
3. 用 GitHub Actions 把關。在 .github/workflows 加 CI,推送時自動跑 lint、type check、測試。設定分支保護規則,讓檢查未過的 PR 無法合併進 main。
4. 環境分層管理。把變數明確分成 Development / Preview / Production 三層,測試金鑰與正式金鑰分開。本機用 vercel env pull 同步,避免人工複製貼上出錯。
5. 善用平台的回滾與觀測。熟悉儀表板的 Deployments 列表、一鍵 Rollback、以及部署日誌與函式記錄。出狀況時,先回滾止血,再從日誌定位原因。
① docs.github.com——Git 與 GitHub 協作、Pull Request、Actions 的權威說明。
② vercel.com/docs——專案設定、環境變數、Functions 與 vercel.ts 設定。
③ developers.cloudflare.com——Workers、Pages、D1 / R2 / KV 與 wrangler 指令參考。