為什麼要把 Docusaurus 部署到 Vercel？
想把文件站或技術 Blog 快速上線，而且想要自動化預覽部署（Preview Deployments）、自動 HTTPS、以及跟 GitHub 完美串接？把 Docusaurus 部署到 Vercel 是很常見且省時的選擇。本文示範一步一步從本機建立到把 Docusaurus 部署到 Vercel 的完整流程，並整理常見問題與調整技巧，讓你能快速上線並保持 CI/CD 流程順暢。
前置條件（你需要準備）
- 已安裝 Node.js（建議使用 LTS，例如 Node 16 或以上）。連結：Node.js（https://nodejs.org）
- GitHub 帳號與倉庫（或其他 Git provider）。連結：GitHub（https://github.com）
- Vercel 帳號（免費方案已足夠開始）。連結：Vercel（https://vercel.com）
- 已安裝 npm 或 yarn（你慣用哪個用哪個）。連結：npm（https://www.npmjs.com） 、 Yarn（https://yarnpkg.com）
- Docusaurus 專案（新建或現有）。連結：Docusaurus（https://docusaurus.io）
快速流程總覽（一步到位）
- 用 Docusaurus 建站（或在既有專案確認可 build）。
- 把程式碼推到 GitHub。
- 在 Vercel 建置新專案並連接 GitHub 倉庫。
- 設定 Build Command 與輸出資料夾（build）。
- 部署、設定自訂網域與 SSL。
下面分段詳細說明每一步。
1) 建立或準備你的 Docusaurus 專案
如果還沒有專案，快速建一個：
- 使用 Docusaurus 官方指令（範例）：
- npx create-docusaurus@latest my-website classic
- cd my-website
- npm run start（本機開發）
- 確認 build 指令能正常運作：
- npm run build 會產生靜態檔案到 build/（Docusaurus 預設）
提示：若你用 monorepo 或 workspace，稍後在 Vercel 的 Project Settings 要指定正確的 Root Directory。
2) 把程式碼推上 GitHub
- 在本機初始化 git、推上 GitHub：
- git init
- git add .
- git commit -m “Init Docusaurus site”
- git remote add origin git@github.com:yourname/your-repo.git
- git push -u origin main
- 推上後確認 repo 有 package.json 與網站源碼。
3) 在 Vercel 建置專案並連接 GitHub
- 登入 Vercel，選擇 “New Project” → Import Git Repository → 選你的 GitHub 倉庫。連結：Vercel（https://vercel.com）
- Vercel 會自動偵測專案類型，但你應該手動確認以下設定：
- Framework Preset: Other 或選 Static Site（也可以選 Docusaurus 若有）
- Build Command: npm run build 或 yarn build
- Output Directory: build
- 如果專案放在子資料夾（例如 /website），在 Import 時設定 Root Directory。
4) 設定環境變數與 baseUrl（必要時）
- 若你的 Docusaurus 在 docusaurus.config.js 裡有 baseUrl 設定（例如部署在子路徑），確認 baseUrl 與 Vercel 的路徑設定一致；通常部署到 Vercel 的根域名時，baseUrl 設為 “/”。
- 若使用 API keys 或第三方服務，於 Vercel Project → Settings → Environment Variables 加入（不要把敏感資訊放在 repo）。
5) 部署與檢查
- 在 Vercel 完成 import 後會自動開始 First Deploy；也會在每次 push 到指定分支時自動部署並在 Pull Request 時建立 Preview Deployments。
- 部署成功後會得到一個 *.vercel.app 的網址，檢查首頁、subpages、assets、JS/CSS 是否載入正常。
- 自訂網域：在 Vercel 設定 Domain，跟隨步驟把 DNS 指向 Vercel（A / CNAME），Vercel 會自動幫你申請 SSL。
常見問題與解法
- 無法 build 或找不到輸出資料夾：
- 確認 Build Command 是 npm run build（不是 npm run start），Output Directory 設為 build。
- 靜態資源 404：
- 檢查 docusaurus.config.js 內的 baseUrl 是否為 “/”（若你在根域名上），或對應子路徑。
- Monorepo 場景：
- 在 Vercel 的 Import 設定 Root Directory 為子專案目錄，並確保安裝與 build 指令以該目錄為上下文。
- Node 版本不對：
- 在 package.json 裡指定 engines.node，或在 Vercel 的 Project Settings 指定 Node 版本。
常用命令一覽（表格）
以下表格列出常用指令與說明（Markdown 表格）：
| 指令或資源 | 連結（Title + Link） | 說明 |
|---|---|---|
| Docusaurus 官方網站 | Docusaurus | 官方文件、快速上手與設定範例 |
| Vercel 平台 | Vercel | 部署、預覽與自動化 CI/CD |
| GitHub | GitHub | 儲存與版本控制倉庫 |
| Node.js | Node.js | 執行環境，建議使用 LTS 版本 |
| npm | npm | 套件管理器 |
| yarn | Yarn | 另一套套件管理器（可選） |
部署範例設定（在 Vercel 頁面上）
- Build Command: npm run build
- Output Directory: build
- Root Directory: （空白，或填入子資料夾名稱）
- Environment Variables: NODE_ENV=production（若需要其他 keys，請加入）
最佳實務與小技巧
- 使用 Preview Deployments 檢視 PR 的實際樣子，這讓多人的文件協作變得更安心。
- 若你經常修改 baseUrl 或對靜態資源有特殊需求，將測試部署納入 CI（例如在 PR 時自動執行 npm run build）以提前發現錯誤。
- 若想要更快的 cold-start，開啟 Vercel 的 Build Cache（大多已自動處理）。
- 若有自訂路由或 rewrites，利用 Vercel 的 rewrites / redirects 設定來處理 legacy URL。
範例：快速 checklist（部署前）
- 確認 npm run build 可在本機順利執行並產生 build/。
- repo 已上傳 GitHub。
- Vercel import 時指定正確 Root Directory（若有）。
- Build Command 與 Output Directory 設為 npm run build、build。
- 所需 env vars 已加入 Vercel。
- 自訂網域與 DNS 設定就緒（如需要）。
常見錯誤與快速修復（FAQ）
-
Q：為什麼資源載入時會出現 404？
A：通常是 baseUrl 設定錯誤或 Output Directory 沒填對。把 baseUrl 設為 “/”（若部署在根域名），並在 Vercel 設定裡把 Output Directory 設為 build。 -
Q：Preview Deployments 沒出現？
A：確認你在 Vercel 使用的 Git provider（GitHub）有授權 Vercel 存取倉庫，且 webhooks 正常建立。
結語 — 快速小結
部署 Docusaurus 到 Vercel 是一個相當直接的流程：確保專案本機可以 build → 推到 GitHub → 在 Vercel import 並設定 Build Command 與 Output Directory → 部署並設定網域與 SSL。利用 Vercel 的自動化與 Preview 功能，可以把文件站的開發與發佈流程做到既快速又穩定。部署 Docusaurus 到 Vercel，不但省時，也能讓團隊在 PR 階段就看到真實的網站狀態──這對文件品質提升非常有幫助。
作者（Author）
- Erik Chen — 個人觀點：把 Docusaurus 部署到 Vercel 是一條「可維護且高效率」的路線，特別適合需要頻繁更新文件的團隊；透過 Preview Deployments 能大幅降低部署風險。Author Link: https://www.linkedin.com/in/erikchen/