Deploy to Vercel

部署 Next.js 應用於 Vercel，具生產配置。

適用時機

• 首次部署 Next.js 應用
• 為 pull request 設預覽部署
• 配自定網域
• 於生產管環境變數

輸入

• 必需：可於本地成功建置之 Next.js 應用
• 必需：GitHub 儲存庫（建議）或本地專案
• 可選：自定網域
• 可選：生產用之環境變數

步驟

步驟一：驗本地建置

npm run build

預期： 建置成功，無誤。

失敗時： 部署前修建置錯誤。常見：TypeScript 錯誤、缺失依賴、無效 import。

步驟二：裝 Vercel CLI

npm install -g vercel

預期： vercel 指令於全域可用，vercel --version 印已裝之版本。

失敗時： 若權限錯誤，用 sudo npm install -g vercel 或配 npm 用用戶本地前綴。以 node --version 驗 Node.js 已裝。

步驟三：連結並部署

# Login to Vercel
vercel login

# Deploy (first time: creates project)
vercel

# Follow prompts:
# - Set up and deploy? Y
# - Which scope? (select your account)
# - Link to existing project? N (for new projects)
# - Project name: my-app
# - Directory: ./
# - Override settings? N

預期： 生預覽 URL（如 https://my-app-xxx.vercel.app）。

失敗時： 若 vercel login 失敗，查網路連接並試基於瀏覽器之認證。若部署失敗，檢視建置輸出之錯誤——Vercel 用乾淨環境，故所有依賴須於 package.json。

步驟四：配環境變數

# Add environment variables
vercel env add DATABASE_URL production
vercel env add API_KEY production preview

# List environment variables
vercel env ls

或透過 Vercel 儀表板配：Project Settings > Environment Variables。

預期： vercel env ls 示所有必需之環境變數已為正確環境（production、preview、development）配置。

失敗時： 若變數於運行時未現，驗目標環境合（production 與 preview）。加變數後重部署——既有部署不自動採新變數。

步驟五：部署至生產

vercel --prod

預期： 生產 URL 可用（如 https://my-app.vercel.app）。

失敗時： 以 vercel logs 或於 Vercel 儀表板查部署日誌。常見問題含生產環境中缺環境變數與建置指令異於本地設定。

步驟六：連結 GitHub 以自動部署（建議）

1. 往 https://vercel.com/new
2. 匯入 GitHub 儲存庫
3. Vercel 自動於此時部署：
   • 推至 main -> 生產部署
   • Pull request -> 預覽部署

預期： Vercel 儀表板示 GitHub 儲存庫已連，後續推至 main 自動觸發生產部署。

失敗時： 若儲存庫不現於匯入列表，查 Vercel GitHub 應用有儲存庫之存取權。往 GitHub Settings > Applications > Vercel 授權。

步驟七：配自定網域

vercel domains add my-domain.com

或透過儀表板：Project Settings > Domains。

依 Vercel 指示更 DNS 紀錄（通常為 CNAME 或 A 紀錄）。

預期： vercel domains ls 示自定網域已配，DNS 傳播後（可達 48 小時），網域解析至 Vercel 部署。

失敗時： 若網域示「Invalid Configuration」，驗 DNS 紀錄精確合 Vercel 之指示。以 dig my-domain.com 或線上 DNS 檢查器確認傳播。

步驟八：優化配置

建 vercel.json 以供高級設定：

{
  "framework": "nextjs",
  "regions": ["iad1"],
  "headers": [
    {
      "source": "/api/(.*)",
      "headers": [
        { "key": "Cache-Control", "value": "no-store" }
      ]
    }
  ]
}

預期： vercel.json 存於專案根目錄，次部署採該配置（於 Vercel 儀表板建置日誌可見）。

失敗時： 若配置被忽略，以 jq . vercel.json 驗 vercel.json 為有效 JSON。查 Vercel 文檔合框架版本，某些設定可能已遷至 next.config.ts。

驗證

• npm run build 於本地成功
• 預覽部署運作且可達
• 生產部署正確服務應用
• 環境變數於生產可用
• 自定網域解析（若已配）
• GitHub 整合於推時觸發部署

常見陷阱

• 於 Vercel 建置失敗而本地成功：Vercel 用乾淨環境。確所有依賴於 package.json，非僅於全域安裝。
• 缺環境變數：變數須加於 Vercel，非僅於 .env.local。不同環境（production、preview、development）有分離之變數集。
• Node.js 版本不符：於 Project Settings 或 package.json engines 欄設 Node.js 版本。
• 大部署：Vercel 有大小限。用 .vercelignore 排除不必要之檔案。
• API 路由超時：Vercel serverless 函數於 Hobby 方案有 10 秒超時。優化或升級。

相關技能

• scaffold-nextjs-app - 建待部署之應用
• setup-tailwind-typescript - 部署前配樣式
• configure-git-repository - 自動部署整合之 Git 設定