Vercel 部署教學｜從 GitHub 到上線只要 5 分鐘

程式碼寫好了，要怎麼讓別人看到？

答案是：部署到 Vercel。

Vercel 是目前最簡單的前端部署方式。

不需要租伺服器、不需要設定 Nginx、不需要搞 SSL 憑證。

只要把 GitHub 連上去，點幾下，網站就上線了。

這篇文章一步一步教你怎麼做。

部署前準備

開始之前，確認你有這些東西。

必要條件

1. 一個 GitHub 帳號

Vercel 需要連結 Git 儲存庫。

GitHub 是最常用的選擇，GitLab 和 Bitbucket 也可以。

2. 一個前端專案

可以是：
- Next.js
- React（Create React App、Vite）
- Vue / Nuxt
- Svelte / SvelteKit
- Astro
- 純 HTML/CSS/JS

3. 專案已經推到 GitHub

如果還沒有專案，可以用這個指令快速建立：

npx create-next-app@latest my-app
cd my-app
git init
git add .
git commit -m "Initial commit"
git remote add origin https://github.com/你的帳號/my-app.git
git push -u origin main

建議（非必要）

有自己的網域（可以之後再綁定）
了解基本的 Git 操作

準備好了嗎？開始部署！

Step 1：註冊並連結 Git Repository

1.1 前往 Vercel 官網

打開 vercel.com。

點擊右上角的「Sign Up」。

1.2 選擇登入方式

建議用 GitHub 登入。

這樣 Vercel 可以直接存取你的 Repository，省去很多設定。

點擊「Continue with GitHub」，然後授權 Vercel。

其他選項：
- Continue with GitLab
- Continue with Bitbucket
- Continue with Email（需要之後再連結 Git）

1.3 授權 GitHub 權限

GitHub 會問你要授權哪些 Repository。

你可以選：

選項	說明
All repositories	授權所有 Repo（方便但權限較大）
Only select repositories	只授權特定 Repo（推薦）

選擇你要部署的專案，點擊「Install & Authorize」。

1.4 進入 Dashboard

授權完成後，你會看到 Vercel Dashboard。

現在可以開始部署了。

Step 2：選擇專案並設定部署選項

2.1 新增專案

在 Dashboard 點擊「Add New」→「Project」。

你會看到所有已授權的 GitHub Repository。

找到你要部署的專案，點擊「Import」。

如果看不到想要的專案：
- 點擊「Adjust GitHub App Permissions」
- 勾選該 Repository
- 返回 Vercel 重新載入

2.2 Vercel 自動偵測專案類型

Vercel 會自動分析你的程式碼，判斷專案類型。

偵測結果範例（Next.js 專案）：

Framework Preset: Next.js
Root Directory: ./
Build Command: next build（自動偵測）
Output Directory: .next（自動偵測）
Install Command: npm install（自動偵測）

常見框架的自動偵測：

框架	Build Command	Output Directory
Next.js	`next build`	`.next`
React (CRA)	`react-scripts build`	`build`
React (Vite)	`vite build`	`dist`
Vue (Vite)	`vite build`	`dist`
Nuxt	`nuxt build`	`.nuxt`
Astro	`astro build`	`dist`

大多數情況，自動偵測是正確的，不需要修改。

2.3 手動調整設定（如果需要）

如果自動偵測錯誤，展開「Build and Output Settings」手動調整：

Build Command：

告訴 Vercel 怎麼 build 你的專案。

# 常見的 build 指令
npm run build
yarn build
pnpm build

Output Directory：

build 完成後，檔案在哪個資料夾。

# 常見的輸出目錄
dist        # Vite 專案
build       # Create React App
.next       # Next.js
out         # Next.js 靜態輸出
public      # 純靜態網站

Root Directory：

如果你的專案是 Monorepo，在這裡指定子目錄。

# 範例：Monorepo 架構
/
├── packages/
│   ├── frontend/    ← 指定這個
│   └── backend/

設定有問題不知道怎麼填？可以聯繫我們讓工程師幫你看。

Step 3：設定環境變數（Environment Variables）

如果你的專案需要環境變數，在這一步設定。

3.1 什麼是環境變數？

環境變數是存放敏感資訊的地方，比如：

API Key
資料庫連線字串
第三方服務密鑰
各種設定值

這些資訊不應該直接寫在程式碼裡。

3.2 在 Vercel 設定環境變數

在部署頁面找到「Environment Variables」區塊。

點擊「Add」，輸入 Key 和 Value：

範例：

Key	Value	說明
`DATABASE_URL`	`postgresql://user:pass@host/db`	資料庫連線
`API_KEY`	`sk-xxxxxxxx`	API 金鑰
`NEXT_PUBLIC_GA_ID`	`G-XXXXXXXXX`	Google Analytics

3.3 環境變數的作用範圍

Vercel 讓你針對不同環境設定不同的值：

環境	說明	使用情境
Production	正式環境	主要網站
Preview	預覽環境	PR 預覽版本
Development	開發環境	本地開發（vercel dev）

你可以：

勾選全部：同一個值用於所有環境
分別設定：測試環境用測試 API，正式環境用正式 API

3.4 特別注意：前端可見的環境變數

Next.js 專案：

NEXT_PUBLIC_ 開頭的變數會暴露給前端。

NEXT_PUBLIC_API_URL=https://api.example.com  ← 前端可見
API_SECRET=xxxxx                              ← 只有後端可見

Vite 專案：

VITE_ 開頭的變數會暴露給前端。

VITE_API_URL=https://api.example.com  ← 前端可見
DB_PASSWORD=xxxxx                      ← 只有後端可見

重要： 機密資訊（密碼、API Secret）不要加這些前綴！

詳細教學：Vercel 環境變數設定完整教學

Step 4：開始部署並等待結果

4.1 點擊 Deploy

設定都確認好了，點擊「Deploy」按鈕。

Vercel 會開始執行部署流程。

4.2 部署流程

你會看到即時的 Build Log：

Cloning github.com/your-username/your-project...
Installing dependencies...
npm install

Running build command...
npm run build

Creating optimized production build...
✓ Compiled successfully

Deploying to Vercel...
✓ Deployment complete!

整個過程通常 1-3 分鐘，取決於專案大小。

4.3 部署成功

部署完成後，你會看到：

🎉 Congratulations! Your project has been deployed.

Production URL: https://your-project.vercel.app

點擊這個網址，你的網站就上線了！

4.4 部署失敗怎麼辦？

如果看到紅色的錯誤訊息：

1. 看 Build Log

展開錯誤區塊，看具體的錯誤訊息。

2. 常見錯誤：

錯誤	原因	解法
`Module not found`	少安裝套件	確認 package.json 有包含
`Command not found`	Build 指令錯誤	檢查 Build Command 設定
`ENOENT`	檔案路徑錯誤	檢查檔案名稱大小寫
`Environment variable not found`	環境變數沒設定	去 Settings 加環境變數

3. 查詢錯誤解法

大多數錯誤在 Google 都找得到答案。

或參考：Vercel 404 Not Found 完整解決方案

還是解不了？可以聯繫我們讓工程師直接幫你處理。

Step 5：綁定自訂網域

預設網址是 xxx.vercel.app，想用自己的網域？

5.1 進入 Domains 設定

在 Project Dashboard，點擊「Settings」
左側選單選擇「Domains」
輸入你的網域，例如 example.com

5.2 設定 DNS

Vercel 會告訴你需要加什麼 DNS 記錄。

方式一：使用 Vercel Nameservers（推薦）

把網域的 Nameserver 改成 Vercel 的：

ns1.vercel-dns.com
ns2.vercel-dns.com

這樣 Vercel 會自動管理所有 DNS 設定。

方式二：使用 CNAME（維持原本的 DNS）

在你的 DNS 服務商加入：

Type	Name	Value
CNAME	@	cname.vercel-dns.com
CNAME	www	cname.vercel-dns.com

常見 DNS 服務商設定位置：

Cloudflare： DNS → 新增記錄
GoDaddy： DNS 管理 → 新增
Namecheap： Advanced DNS → 新增記錄
Google Domains： DNS → 自訂記錄

5.3 等待 DNS 生效

DNS 設定後需要等待生效：

快的話：幾分鐘
慢的話：最多 48 小時（通常不會這麼久）

Vercel 會顯示狀態：

✓ Valid Configuration
✓ SSL Certificate Issued

看到這兩個綠勾，就完成了！

5.4 HTTPS 自動設定

Vercel 會自動幫你申請 SSL 憑證。

不需要額外設定，不需要付費。

你的網站會自動啟用 HTTPS。

部署後管理

網站上線後，還有這些事可以做。

查看部署紀錄

在 Project Dashboard → Deployments：

所有部署歷史
每次部署的狀態（成功/失敗）
每次部署的獨立網址
Build Log 和 Function Log

回滾到之前的版本

發現新版本有 bug？

找到之前正常的部署
點擊右邊的「...」選單
選擇「Promote to Production」

舊版本立刻變成正式版。

查看訪客數據

Web Analytics（免費）：

Settings → Analytics → Enable

可以看到：
- 頁面瀏覽量
- 訪客來源
- 裝置分布

Speed Insights（Pro）：

可以看到 Core Web Vitals 等效能數據。

設定自動部署分支

預設只有 main 分支會觸發正式部署。

你可以在 Settings → Git 調整：

Production Branch： 哪個分支部署到正式環境
Preview Branches： 哪些分支會觸發預覽部署

常見部署問題排解

部署時最常遇到的問題。

問題 1：Build 失敗

症狀： 部署時看到紅色錯誤

排查步驟：

展開 Build Log 看錯誤訊息
複製錯誤訊息去 Google 搜尋
檢查 package.json 的依賴是否正確
確認本地 npm run build 可以成功

常見原因：

TypeScript 型別錯誤
ESLint 錯誤（如果設定為 build 時檢查）
缺少環境變數
套件版本衝突

問題 2：部署成功但頁面 404

症狀： Build 成功，但開啟網址顯示 404

可能原因：

Output Directory 錯誤
- 確認 Vercel 設定的 Output Directory 和實際輸出一致
SPA 路由問題
- React Router / Vue Router 需要設定 rewrites
- 在 vercel.json 加入：

{
  "rewrites": [
    { "source": "/(.*)", "destination": "/index.html" }
  ]
}

檔案大小寫問題
- Windows/Mac 對大小寫不敏感
- Linux（Vercel）對大小寫敏感
- 檢查 import 路徑大小寫是否正確

詳細解法：Vercel 404 Not Found 完整解決方案

問題 3：環境變數讀不到

症狀： 程式碼讀取環境變數得到 undefined

排查步驟：

確認變數名稱完全正確（包含大小寫）
確認有勾選正確的環境（Production/Preview/Development）
設定後要重新部署才會生效
前端變數要加 NEXT_PUBLIC_ 或 VITE_ 前綴

問題 4：部署很慢

可能原因：

專案太大
安裝了太多依賴
Build 指令太複雜

改善方法：

使用 .vercelignore 排除不需要的檔案
優化依賴，移除沒用到的套件
使用 npm ci 而非 npm install

常見問題 FAQ

Q1：Vercel 部署要多久？

通常 1-3 分鐘。

大型專案可能 5-10 分鐘。

如果超過 45 分鐘會自動超時失敗。

Q2：每次推 code 都會自動部署嗎？

是的，這就是 Vercel 的特色。

推到 main 分支 → 更新正式網站
推到其他分支 → 產生預覽網址
開 PR → 產生 PR 預覽網址

Q3：可以關閉自動部署嗎？

可以。

Settings → Git → 關閉相關選項

但建議保持開啟，這是 Vercel 最方便的地方。

Q4：部署後可以看程式碼嗎？

別人看不到你的原始碼。

Vercel 部署的是 Build 後的檔案，不是原始碼。

Q5：Vercel 支援什麼語言？

前端： 幾乎都支援（React、Vue、Angular、Svelte...）

後端（Serverless Functions）：
- Node.js
- Python
- Go
- Ruby

Q6：可以部署後端專案嗎？

可以用 Serverless Functions，但有限制：

最長執行時間 10-60 秒
不支援長連線（WebSocket 有限制）
不支援傳統 MVC 框架

完整後端建議用 Render 或 Railway。

下一步學習

恭喜你完成第一次 Vercel 部署！

接下來可以學習：

入門者

進階使用

框架專屬教學

問題排解

Vercel 部署失敗？

Build Error、環境變數、自訂網域，我們幫你快速排除問題。

解決 Vercel 問題