---

name: deploy-to-vercel locale: wenyan source_locale: en source_commit: 82c77053 fence_basis_commit: 82c77053 translator: "Julius Brussee homage — caveman" translation_date: "2026-04-19" description: > Deploy a Next.js application to Vercel. Covers project linking, environment variables, preview deployments, custom domains, and production deployment configuration. Use when deploying a Next.js app for the first time, setting up preview deployments for pull requests, configuring custom domains, or managing environment variables in a production Vercel deployment. license: MIT allowed-tools: Read Write Edit Bash Grep Glob metadata: author: Philipp Thoss version: "1.0" domain: web-dev complexity: basic language: TypeScript tags: vercel, deployment, nextjs, hosting, ci-cd

部至 Vercel

將 Next.js 應用部至 Vercel，具產配。

用時

• 首次部 Next.js 應用
• 為 pull request 立預覽部署
• 配自定域名
• 理產中環境變量

入

• 必要：本地可成建之 Next.js 應用
• 必要：GitHub 庫（宜）或本地項目
• 可選：自定域名
• 可選：產用環境變量

法

第一步：驗本地建

npm run build

得： 建成無錯。

敗則： 部前修建錯。常見：TypeScript 錯、缺依賴、無效導入。

第二步：裝 Vercel CLI

npm install -g vercel

得： vercel 命全局可用，vercel --version 印已裝之版。

敗則： 若權錯，用 sudo npm install -g vercel 或設 npm 用 user-local 前綴。以 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 或於控制臺察部署日誌。常見問題含產環境缺變量、建命與本地異。

第六步：連 GitHub 以自動部（宜）

1. 至 https://vercel.com/new
2. 導入爾之 GitHub 庫
3. Vercel 自動部：
   • 推至 main -> 產部
   • Pull request -> 預覽部

得： Vercel 控制臺示 GitHub 庫已連，後推至 main 自動觸產部。

敗則： 若庫於導入單不現，察 Vercel GitHub app 可訪該庫。至 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 驗 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 無服函數於 Hobby 有 10s 超時。優或升。

Related Skills

• scaffold-nextjs-app - 建可部之應用
• setup-tailwind-typescript - 部前配樣式
• configure-git-repository - 自動部集成之 Git 設