使用手冊

內部開發指南 · 地端到生產環境

在地端用 Claude 開發, 一條 Git 流程部署到雲端。

給團隊的部署實戰手冊：地端用 Claude Code 開發,如何完成 Claude 登入驗證,並把成果透過 Git 推送到 GitHub,自動部署到 Vercel 與 Cloudflare。含標準工作流、三大平台知識與邏輯、登入驗證教學。

這份手冊假設你從零開始——沒寫過程式、沒用過終端機也沒關係。它會帶你一步步把電腦準備好、建立三個平台帳號、完成 Claude Code 登入,理解 AI 開發到底怎麼運作,接著用一條固定的 Git 流程把作品自動部署到 Vercel 或 Cloudflare。讀完你會擁有一套可以每天重複的工作流:在自己電腦上開發,推送一次,網站自動上線。

閱讀時間
17 分
更新日期
開啟原始報告
部署平台 · GitHub / Vercel / Cloudflare
3
Git 唯一真實來源
1
Claude 驗證模式
2
每次推送一個預覽環境
PR
本頁章節

01先建立心智模型

地端負責寫, GitHub 負責記, 雲端負責跑。

部署看起來複雜,是因為三件事被混在一起談。把它們拆開,整套流程就只有一個方向。第一件事是地端開發:你的電腦,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)。預覽與生產用的是同一份建置流程,所以「在預覽看起來對」基本上等於「上線也會對」。

  1. 地端開發

  2. Commit

  3. Push

  4. PR Preview

  5. Review

  6. Merge main

  7. Production

不要記「怎麼上傳到 Vercel」。 記「怎麼 push 到 GitHub」就好—— 剩下的部署,平台自己會做。

這份手冊的單一核心觀念

先認識這些詞,後面就不卡

這份手冊會重複用到一組詞。你不用背,先看過一遍,讀到時知道它在講什麼即可。它們大致對應設計工作裡你已經熟悉的概念。

術語白話解釋設計類比
終端機 / 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 / 部署把建置好的網站放到公開網址上,讓任何人能開。把作品發佈成公開連結
環境變數不寫進程式碼、另外保管的設定值(多為密鑰)。不該外流的密碼,單獨鎖起來

02從零開始 · 一次設定好

把電腦準備好, 這些只做一次。

這一節是一次性設定,做完之後日常開發都不用再碰。預估約 30 到 40 分鐘。以下以 macOS 為例(Tenten 設計師多用 Mac);Windows 大原則相同,建議改用 WSL2 取得近似的環境。照順序做,每一步做完再進下一步。

第一步 · 打開終端機

終端機是後面所有指令的舞台。在 Mac 上按 Cmd + 空白鍵 開啟 Spotlight,輸入「Terminal」按 Enter,就會出現一個可以打字的視窗。看到一行以 $ 或 % 結尾的提示符號就代表它在等你下指令。本手冊的指令,複製貼上後按 Enter 即可執行。

第二步 · 安裝 Homebrew(套件管理器)

Homebrew 是 Mac 上安裝開發工具的標準方式,之後用一行 brew install 就能裝好各種工具。把下面這行貼進終端機執行,過程會請你輸入電腦密碼(輸入時不會顯示字元,是正常的)。

bash
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# 裝完依畫面提示,可能要再貼一兩行把 brew 加進 PATH
brew --version    # 出現版本號就成功

第三步 · 安裝 Node.js 與 Git

Node.js 是執行前端工具與 CLI 的引擎(npm 也隨它一起裝好);Git 是版本控制工具。用 Homebrew 一次裝齊,再用 -v / --version 確認。看到版本號就代表成功。

bash
brew install node git

# 確認都裝好了
node -v          # 例如 v24.x(建議用 LTS 版)
npm -v
git --version

第四步 · 安裝編輯器 VS Code

VS Code 是免費的程式碼編輯器,用來開啟、檢視專案檔案,也是 Claude Code 的好搭檔。到 code.visualstudio.com 下載安裝。Claude Code 在 VS Code 內有官方擴充套件,能在編輯器裡直接看到它修改了哪些檔案、哪幾行——對習慣看視覺差異的設計師特別友善。

第五步 · 註冊四個帳號

工具就緒後,註冊這四個帳號。建議都用同一個公司 email,並且 Vercel 與 Cloudflare 都選「用 GitHub 帳號登入」,日後連結倉庫最省事。

帳號註冊網址用途
Claudeclaude.aiClaude Code 的訂閱帳號(Pro / Max),用來驗證登入
GitHubgithub.com保管程式碼與歷史,是雲端部署的來源
Vercelvercel.com部署平台 A;註冊時選「Continue with GitHub」
Cloudflaredash.cloudflare.com部署平台 B(Pages / Workers)

第六步 · 安裝三個命令列工具

最後裝齊三個會天天用到的 CLI:Claude Code 本身、Vercel 的 vercel、Cloudflare 的 wrangler。用 npm install -g 做全域安裝(-g 代表整台電腦都能用)。

bash
npm install -g @anthropic-ai/claude-code   # Claude Code
npm install -g vercel                    # Vercel CLI
npm install -g wrangler                  # Cloudflare CLI

# 確認三個都裝好
claude --version
vercel --version
wrangler --version

03地端驗證 · 讓工具認得你

讓 Claude 與三個平台都登入你的帳號。

工具裝好了,還要讓它們知道「你是誰」。這節把 Claude Code 與三個平台的登入一次做完。全部走瀏覽器授權(OAuth),不需要手動複製貼上任何金鑰。

Claude Code 登入:兩種驗證模式

進到任一資料夾,輸入 claude 啟動。第一次會引導你登入,先選驗證方式。模式 A 是 Claude 訂閱帳號(Pro / Max):走 OAuth,Claude Code 會開瀏覽器到 claude.ai,你按授權就自動帶回憑證,用量算在訂閱方案裡——多數同事用這個。模式 B 是 Anthropic Console API Key:用 API 按量計費,把金鑰設成環境變數 ANTHROPIC_API_KEY。登入後憑證存在本機(macOS 存於系統 Keychain),之後不用重登。

bash
# 模式 A:訂閱帳號 OAuth(最常用)
claude                 # 啟動後選「Claude account」,瀏覽器按授權
# 進到 Claude 對話後,隨時可切換或登出:
#   /login    切換 / 重新登入
#   /logout   登出目前帳號

# 模式 B:改用 Anthropic Console API Key
export ANTHROPIC_API_KEY="sk-ant-..."   # 放進 ~/.zshrc 持久化

登入 GitHub、Vercel、Cloudflare

程式碼要推上 GitHub、雲端要連到 GitHub,所以這三個帳號也要在終端機登入。GitHub 用官方 gh CLI(用 Homebrew 裝),其餘各跑一次 login。同樣都是開瀏覽器授權。

bash
brew install gh       # 先裝 GitHub CLI

gh auth login         # 選 GitHub.com → HTTPS → Login with browser
vercel login          # 用 GitHub 帳號授權
wrangler login        # 開瀏覽器授權 Workers / Pages 權限

# 第一次用 Git,設定身分(會寫進每個 commit)
git config --global user.name  "你的名字"
git config --global user.email "you@tenten.co"

04AI 工作流 · 怎麼跟它一起做事

Claude Code 不是聊天機器人, 是會動手的工程夥伴。

和網頁版聊天最大的差別:Claude Code 跑在你的終端機裡,能直接讀寫專案檔案、執行指令、跑測試。你不必把程式碼複製來貼去——你描述要什麼,它實際動手改你的專案。把它想成一位坐在你旁邊、會打字的工程師:你給方向、做決定、驗收成果,鍵盤的事交給它。

啟動與對話

先用 cd 進到你的專案資料夾,輸入 claude 啟動,然後直接用中文描述你要做的事。具體一點會更準——與其說「做個表單」,不如說「在聯絡頁加一個含姓名、email、訊息三欄的表單,送出後顯示成功訊息」。

bash
cd ~/projects/tenten-site   # 進到你的專案資料夾
claude                       # 啟動,接著直接打字描述需求

三種互動模式:用 Shift + Tab 切換

Claude Code 有三種運作模式,按 Shift + Tab 循環切換,畫面下方會顯示目前模式。對設計師來說,剛開始建議多用「規劃模式」:先讓它把計畫講清楚、你看過再動手,最安全。

模式它會怎麼做什麼時候用
一般模式每次要改檔案或跑指令前,先問你同意預設;邊做邊確認
規劃模式 Plan只研究與提計畫,先不動任何檔案複雜需求;先對齊方向再執行
自動接受編輯不再逐次詢問,自動套用編輯你已信任這輪任務、想加速時

幾個天天用得到的指令

在 Claude 對話中以斜線 / 開頭的是內建指令。記住下面這幾個就夠日常使用。另外,打 @ 可以指定某個檔案帶進對話,按 Esc 可中斷它正在做的事。

指令 · 01

/init

建立專案記憶

掃描整個專案,產生一份 CLAUDE.md,讓 Claude 記住這個專案的結構與慣例。新專案先跑這個。

指令 · 02

/clear

清空脈絡

換一個不相干的新任務時用,清掉前面的對話脈絡,避免它被舊內容干擾。

指令 · 03

/model

切換模型

在不同 Claude 模型間切換。複雜任務用能力更強的模型,簡單修改可用較快的。

指令 · 04

/help

查說明

列出所有可用的內建指令與快捷鍵。忘記指令時的第一站。

指令 · 05

@檔名

指定檔案

在訊息裡打 @ 接檔名,把特定檔案精準帶進對話,例如「修正 @app/page.tsx 的標題」。

指令 · 06

/login · /logout

帳號切換

重新登入或登出 Claude 帳號。換帳號、或驗證過期時用。

CLAUDE.md:專案的常駐說明書

/init 會在專案根目錄產生一個 CLAUDE.md。它是給 Claude 看的專案說明:用什麼框架、檔案放哪、命名慣例、團隊規則。每次啟動 Claude Code 都會自動讀它,所以把「這個專案的固定規矩」寫進去,就不必每次重講。它本身也是程式碼的一部分,會跟著 commit 進 Git,團隊共享同一份。

審查它的每一次修改

Claude 要改檔案或執行指令前,(在一般模式下)會先列出它打算做什麼、停下來等你按同意。養成看過再放行的習慣:改檔案時看它改了哪幾行,執行指令時看清楚那行指令在做什麼。改完後一定到瀏覽器用 npm run dev 親眼確認效果,不要只看它說「完成了」。

  1. 描述需求

  2. 看它的計畫

  3. 核准

  4. 它改檔案

  5. 本機預覽驗收

  6. 交給 Git

05三大平台 · 基本知識與邏輯

三個平台, 各管一件事。

要看懂部署,先看懂每個平台的職責。GitHub 是版本控制與協作中心,保管程式碼與完整歷史。Vercel 與 Cloudflare 是部署平台,連到你的 GitHub 倉庫,自動把程式碼變成線上服務——兩者定位接近,差別在執行環境與生態。下面把每個平台的核心概念拆成卡片,記住卡片左上角的分組,就知道哪個指令屬於哪個平台。

GitHub · 01

Repository

程式碼倉庫

一個專案一個倉庫,保管所有檔案與每一次變更的歷史。雲端平台就是連到這裡讀程式碼。

GitHub · 02

Commit / Push

提交與推送

commit 把變更存成一個有訊息的快照,push 把這些快照上傳到 GitHub。部署的觸發點就是 push。

GitHub · 03

Branch / Pull Request

分支與審查

在分支上開發不影響 main。開 PR 讓人審查,平台同時給一個預覽網址,合併後才進生產。

GitHub · 04

.github/workflows

Actions / CI

GitHub 內建的自動化:每次推送可自動跑測試、Lint、建置。把錯誤擋在合併之前。

Vercel · 01

vercel link

連結專案

把本機資料夾綁定到一個 Vercel 專案。實務上多在儀表板 Import GitHub 倉庫,之後推送即自動部署。

Vercel · 02

Preview / Production

兩種環境

推到分支或開 PR 產生 Preview 網址;合併進 main 更新 Production。框架(如 Next.js)自動偵測,零設定。

Vercel · 03

vercel env pull

環境變數

密鑰存在 Vercel,用這道指令拉成本機 .env.local。雲端與地端共用同一份設定,不必手抄。

Vercel · 04

Functions

後端函式

前端之外,Vercel 也跑後端。預設 Fluid Compute,支援完整 Node.js、Python 等,適合 API 與全端框架。

Cloudflare · 01

wrangler pages deploy

Pages / 前端

Cloudflare Pages 對應前端與全端網站。一樣可連 Git 自動建置,部署在 Cloudflare 全球邊緣節點。

Cloudflare · 02

wrangler deploy

Workers / 邊緣

Workers 是在離使用者最近的節點執行的後端函式,冷啟動極低,適合 API、邊緣中介層與排程任務。

Cloudflare · 03

wrangler.jsonc

設定檔

宣告路由、相容性日期、以及對資料庫與儲存的繫結(bindings)。Worker 透過繫結存取這些資源。

Cloudflare · 04

D1 / R2 / KV

儲存服務

D1 是 SQL 資料庫,R2 是物件儲存(相容 S3),KV 是鍵值快取。和 Workers 同生態,就近存取。

Vercel 還是 Cloudflare?一張表先有方向

兩者都能部署現代前端與全端應用,且都支援 Git 自動部署。下表是選型時的主要差異點,不是優劣排名——多數團隊會依框架、後端需求與既有生態決定,有時兩者並用。

面向VercelCloudflare
最順的框架Next.js(原生最佳)多框架;Next.js 需 OpenNext 轉接
後端執行Functions · Fluid Compute(完整 Node.js)Workers(邊緣執行,就近低延遲)
內建資料 / 儲存透過 Marketplace 整合D1 · R2 · KV · Durable Objects 原生
命令列工具vercelwrangler
適合場景Next.js 為主的產品、需要完整 Node 後端邊緣優先、用到 Cloudflare 儲存與網路生態

06第一次 · 建立並連結專案

建一個專案, 把它接上 GitHub 與雲端。

前面是工具與觀念,這節第一次把它們串起來:建立一個真的專案,接上 GitHub,再連到 Vercel。這套「連結」每個新專案只做一次,做完之後,日常就只剩下一節要講的每日流程。我們用 Next.js 當範例,它是 Tenten 常用、且 Vercel 原生支援的框架。

1 · 建立一個 Next.js 專案

進到你放專案的資料夾,執行下面這行。它會問幾個問題(專案名稱、要不要 TypeScript、Tailwind 等),不確定就一路按 Enter 用預設值。建好後它已自動幫你做了 Git 初始化與第一個 commit。

bash
cd ~/projects
npx create-next-app@latest tenten-site   # 依提示選擇,預設即可
cd tenten-site

2 · 在本機跑起來看看

部署之前,先在自己電腦上確認它能跑。npm run dev 會啟動本機伺服器,終端機會印出一個 http://localhost:3000 網址,用瀏覽器打開就能看到預設首頁。這時你可以啟動 claude 開始改它。要停掉伺服器按 Ctrl + C。

bash
npm run dev          # 開瀏覽器看 http://localhost:3000

3 · 推上 GitHub

把這個專案上傳到 GitHub,成為雲端部署的來源。因為 create-next-app 已經初始化 Git,這裡直接用 gh 建立遠端倉庫並推送。--private 代表私有倉庫。

bash
gh repo create tenten-site --private --source=. --remote=origin --push
# 完成後,到 github.com 就能看到這個倉庫

4 · 在 Vercel 匯入這個倉庫

這是把 GitHub 與雲端「綁定」的關鍵一步,只需做一次。打開 vercel.com/new,選擇剛剛建立的 GitHub 倉庫按 Import。Vercel 會自動辨識這是 Next.js 專案、自動填好建置設定,你按 Deploy 即可。幾分鐘後它給你一個正式網址。從這一刻起,這個倉庫每次 push 都會自動部署——你之後不必再回 Vercel 操作。

到這裡,你已經有一個「地端能開發、push 就自動上線」的專案。剩下的,就是把這個循環變成每天的習慣。

07標準工作流 · 每天怎麼跑

一輪開發, 就這十步。

把前面的觀念落成每日操作。下面十張卡片是一個功能從開始到上線的標準順序——前六步是固定流程,後四步是讓流程更穩的實務習慣。第一次設定好專案與 Git 連結後,日常其實只在重複步驟 02 到 06。

開分支,別直接動 main

從最新的 main 拉一個功能分支:git switch -c feat/login-page。main 永遠保持可部署狀態,所有開發都在分支上進行,改壞了也不影響線上。

每個新功能 · 一條分支

在地端用 Claude Code 開發

在專案資料夾啟動 claude,描述你要的功能讓它讀寫檔案、跑測試。改完用 npm run dev 在本機預覽,確認畫面與行為正確再進下一步。

地端 · localhost 先驗證

小步提交,訊息寫清楚

git add -p 挑要進的變更,git commit -m 寫一句說明「做了什麼」。一個 commit 對應一件事,日後回滾與審查都更精準。

commit 是回滾的最小單位

推送並開 Pull Request

git push -u origin feat/login-page 後 gh pr create。推送的瞬間,Vercel / Cloudflare 會自動建一個 Preview 網址,貼在 PR 裡讓你和同事審。

push = 自動產生預覽環境

在 Preview 網址上驗收

不要只看本機。打開 PR 裡的 Preview 連結,那是用正式建置流程跑出來的環境,最接近上線結果。CI 的測試也會在這時跑完並回報通過與否。

Preview 等於上線預演

合併進 main,自動上生產

審查通過後 Squash and merge。合併進 main 會觸發 Production 部署,幾分鐘後正式網址就是最新版本。你全程沒有手動上傳任何檔案。

merge main = 上線

HABIT 07 · 環境變數用平台管理,不進 Git

API 金鑰、資料庫連線字串設在 Vercel / Cloudflare 的環境變數,本機用 vercel env pull 同步。.env 一律加進 .gitignore,密鑰永不進倉庫。

密鑰與程式碼分離

HABIT 08 · 區分 Preview 與 Production 變數

平台可為 Preview 與 Production 設不同變數值。把測試資料庫綁 Preview、正式資料庫綁 Production,預覽環境就不會誤動到線上資料。

環境隔離,避免誤傷

HABIT 09 · 出事就回滾到上一版

線上壞了不必急著修 code。Vercel / Cloudflare 儀表板都能一鍵 Rollback 回上一個正常部署,因為每個版本都對應一個 commit。先止血,再排查。

回滾優先於除錯

HABIT 10 · 讓 Claude Code 幫你跑 Git 與部署

Claude Code 能直接執行 git、gh、vercel、wrangler。你可以請它「開分支、提交、推送並開 PR」,它會逐步執行——但合併與上生產這類動作,讓它先問過你再做。

高風險動作保留人工確認

08實際走查 · 從本機到 Vercel

一個功能, 走完整條部署流程。

以下是一段示意操作:在一個已連到 Vercel 的 Next.js 專案裡,用 Claude Code 新增一個聯絡頁,開分支、提交、推送、取得 Preview 網址、合併上線。重點不在指令本身,而在每一步分別發生在地端、GitHub、還是雲端。Cloudflare 的流程結構相同,只是把 vercel 換成 wrangler。

~/projects/tenten-site · claude code


# ### 地端:開分支,啟動 Claude Code
$ git switch -c feat/contact-page
ok: Switched to a new branch 'feat/contact-page'
$ claude


$ You ›
  在 app/contact 新增一個聯絡頁,含表單與 Tenten 品牌樣式。


claude: Claude ›
  已建立 app/contact/page.tsx 與表單元件,沿用現有設計 token。
# [edited 3 files · app/contact/page.tsx, components/ContactForm.tsx, app/globals.css]


# ### 地端:本機預覽確認
$ npm run dev
# ▲ Next.js · Local: http://localhost:3000/contact  ✓ 畫面正確


# ### 提交並推送(可請 Claude 代跑這幾步)
$ You › 幫我提交這次變更,推送並開一個 PR。


claude: Claude ›
  將執行 git add / commit / push 與 gh pr create:
# git add app/contact components/ContactForm.tsx app/globals.css
# git commit -m "feat: add contact page with branded form"
# git push -u origin feat/contact-page
# gh pr create --fill
ok: ✓ Pull request #28 opened


# ### 雲端:Vercel 偵測到推送,自動建 Preview
# [Vercel] Building feat/contact-page... (依 GitHub 推送觸發)
# [Vercel] Running build · Next.js detected · Node 24
hl: [Vercel] Preview ready ›
  hl: https://tenten-site-git-feat-contact-page.vercel.app
# [GitHub Checks] CI tests passed ✓ · Preview comment posted on #28


# ### 在 Preview 網址上驗收,審查通過後合併
$ gh pr merge 28 --squash
ok: ✓ Pull request #28 merged into main


# ### 雲端:合併進 main → 自動部署 Production
# [Vercel] Deploying main to Production...
ok: [Vercel] ✓ Production ready › https://skills.tenten.co/contact


# ### 對照:同一份程式碼部署到 Cloudflare
$ wrangler pages deploy ./out
ok: ✓ Deployed to https://tenten-site.pages.dev

你全程沒有手動上傳任何檔案。 你只是 push 到 GitHub, Vercel 自己把它變成了線上網站。

— Git 驅動部署的核心:程式碼到網站之間,沒有人工搬運

這段流程的三個關鍵點

**第一,觸發部署的是 git push,不是任何上傳動作。**Vercel 與 Cloudflare 事先連到了這個 GitHub 倉庫,推送一發生就自動拉取、建置、上線。你的職責止於 push。

**第二,Preview 與 Production 是兩個自動分流的環境。**分支 / PR 進 Preview,合併進 main 才上 Production。所以你永遠有一個合併前就能點開檢查的真實網址。

**第三,Claude Code 可以代跑 Git 與部署指令,但邊界要清楚。**讓它處理 add / commit / push / 開 PR 很安全;合併與上生產這類不可逆動作,讓它停下來等你確認再執行。

09卡住了 · 先查這張表

新手最常遇到的八個狀況。

卡關是學習的常態,不是你做錯了什麼。下表是初學者最常撞到的狀況、原因與解法。遇到紅字錯誤先別慌——絕大多數都在這張表裡,而且都救得回來。

你看到的狀況多半是因為怎麼解
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

10最容易踩的雷

上路前, 先避開這幾個坑。

11進階路徑

跑順之後, 再把流程升級。

當基本的「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 指令參考。

部署不是一個高深技術, 是一個固定習慣: 開分支、提交、推送、預覽、合併。

記住這條動線,三個平台都通用