當 Headless Ghost CMS 的靈活遇上 Vercel 的速度：部署的藝術

Aiko · March 29, 2025, 7:17am

如何設定 Headless Ghost CMS 並將其前端部署到 Vercel 平台。本教學將涵蓋從設定 Ghost 以啟用 Headless 模式，到建立一個簡單的前端應用程式來消費其 Content API，再到最終將該前端部署至 Vercel 的完整流程。

前置概念：Headless Ghost CMS 與 Vercel

Headless Ghost CMS：這意味著您僅使用 Ghost 作為後端內容管理系統。您利用其強大的編輯器和內容組織功能來創建和管理內容。然而，內容的呈現（即網站的「頭部」）將由一個獨立的前端應用程式負責。Ghost 透過其 Content API 提供內容給這個前端應用程式。
Vercel：這是一個專為前端開發者設計的雲端平台，特別擅長部署基於 JavaScript 的應用程式，尤其是使用 Next.js, React, Vue 等框架的應用。它提供全球 CDN、自動 CI/CD、伺服器渲染支援和無伺服器功能，是部署 Headless CMS 前端的理想選擇。

核心流程概覽：

設定 Ghost CMS：確保您的 Ghost 實例正在運行，並取得必要的 Content API 金鑰。
建立前端應用程式：使用您選擇的框架（我們將以 Next.js 作為範例）建立一個新的前端專案。
連接 Ghost Content API：在前端應用程式中設定並使用 Ghost Content API SDK 來獲取內容。
部署到 Vercel：將您的前端應用程式連接到 Vercel 並進行部署。
設定 Webhooks (建議)：配置 Ghost 在內容更新時自動觸發 Vercel 重新部署。

步驟一：設定 Ghost CMS 並取得 API 金鑰

無論您是使用 Ghost(Pro) 還是自架設 Ghost（例如使用 Docker 或在 DigitalOcean 等伺服器上），您都需要執行以下步驟來為 Headless 操作做準備：

確保 Ghost 運行且可公開訪問：您的 Ghost 網站必須在線上運行，並且有一個可供前端應用程式訪問的 URL。這個 URL 將是您的 API URL 的基礎。
登入 Ghost 管理後台：使用您的管理員帳號登入您的 Ghost 網站後台（通常是 yourdomain.com/ghost）。
導航至 Integrations：在左側邊欄中，點擊 “Settings”，然後選擇 “Integrations”。
建立 Custom Integration：
- 向下滾動到 “Custom Integrations” 部分。
- 點擊 “Add custom integration”。
- 為您的整合命名（例如 “Vercel Frontend” 或 “Next.js Site”）。
- 點擊 “Create”。
複製 API 金鑰和 URL：
- 在建立整合後，您將看到以下關鍵資訊：
  - Content API Key：這是您的前端應用程式用來向 Ghost 請求內容的公開金鑰。請複製並妥善保管此金鑰。
  - Admin API Key：此金鑰具有寫入權限，通常不應在前端公開使用。在 Headless 設置中，我們主要關注 Content API Key。
  - API URL：這是您的 Ghost 實例的 API 端點 URL。請複製並妥善保管此 URL。

重要提示：Content API Key 是設計為可以公開暴露在前端程式碼中的（雖然更推薦使用環境變數），而 Admin API Key 絕對不能暴露。

現在，您已經擁有了連接前端所需的 API URL 和 Content API Key。

步驟二：建立前端應用程式 (以 Next.js 為例)

我們將使用 Next.js 作為範例，因為它與 Vercel 整合得非常好，並且非常適合建構由 CMS 驅動的網站。

開啟您的終端機 (Terminal)。

執行 Create Next App 指令：

npx create-next-app@latest my-ghost-frontend --typescript
# 或者，如果您偏好 JavaScript：
# npx create-next-app@latest my-ghost-frontend

將 my-ghost-frontend 替換為您想要的專案名稱。

進入專案目錄：
```
cd my-ghost-frontend
```
安裝 Ghost Content API SDK：這是官方提供的 JavaScript 函式庫，用於簡化與 Ghost Content API 的互動。
```
npm install @tryghost/content-api
# 或使用 yarn：
# yarn add @tryghost/content-api
```
設定環境變數：為了安全地管理您的 API 金鑰和 URL，我們將使用環境變數。在專案根目錄建立一個名為 .env.local 的檔案。
- 重要：確保將 .env.local 加入到您的 .gitignore 檔案中，以防止意外將敏感金鑰提交到版本控制系統。create-next-app 通常會自動處理此步驟。
- 在 .env.local 檔案中添加以下內容，並將值替換為您在步驟一中複製的實際 API URL 和 Content API Key：
```
# .env.local
NEXT_PUBLIC_GHOST_API_URL=YOUR_API_URL_HERE
NEXT_PUBLIC_GHOST_CONTENT_API_KEY=YOUR_CONTENT_API_KEY_HERE
```
  - 注意：在 Next.js 中，以 NEXT_PUBLIC_ 開頭的環境變數會被暴露給瀏覽器，這對於 Content API Key 是可以接受的，因為它是設計為公開的。如果需要處理敏感金鑰（例如 Admin API Key，雖然此範例不使用），則不應加 NEXT_PUBLIC_ 前綴，並且只能在伺服器端（如 getStaticProps 或 getServerSideProps）訪問。

步驟三：連接 Ghost Content API 並獲取內容

現在我們將修改 Next.js 應用程式來從 Ghost 獲取並顯示內容。我們以修改首頁 (pages/index.tsx 或 pages/index.js) 來顯示最新的文章列表為例。

編輯 pages/index.tsx (或 .js)：

import GhostContentAPI from '@tryghost/content-api';
import type { GetStaticProps, InferGetStaticPropsType } from 'next';
import type { PostsOrPages } from '@tryghost/content-api'; // 匯入類型

// 1. 初始化 Ghost Content API 客戶端
const api = new GhostContentAPI({
  url: process.env.NEXT_PUBLIC_GHOST_API_URL || '', // 從環境變數讀取 URL
  key: process.env.NEXT_PUBLIC_GHOST_CONTENT_API_KEY || '', // 從環境變數讀取 Key
  version: "v5.0" // 指定 API 版本 (檢查 Ghost 文件以獲取最新穩定版本)
});

// 2. 使用 getStaticProps 在建構時獲取數據 (推薦用於部落格類型網站)
export const getStaticProps: GetStaticProps<{ posts: PostsOrPages }> = async () => {
  try {
    const posts = await api.posts.browse({
      limit: 10, // 獲取最新的 10 篇文章
      include: ['tags', 'authors'] // 同時獲取標籤和作者信息
    });
    return {
      props: { posts },
      revalidate: 60 // 選項：設定 ISR (Incremental Static Regeneration)，每 60 秒嘗試重新生成頁面
    };
  } catch (error) {
    console.error("Error fetching posts from Ghost:", error);
    // 在錯誤情況下返回空陣列或進行其他錯誤處理
    return { props: { posts: [] } };
  }
};

// 3. 建立頁面元件來顯示數據
export default function Home({ posts }: InferGetStaticPropsType<typeof getStaticProps>) {
  return (
    <div>
      <h1>My Ghost Blog Frontend</h1>
      <h2>Latest Posts:</h2>
      {posts.length > 0 ? (
        <ul>
          {posts.map((post) => (
            <li key={post.id}>
              {/* 將來可以連結到文章詳細頁面 */}
              <a href={`/posts/${post.slug}`}>{post.title}</a>
              {post.primary_author && <p>By {post.primary_author.name}</p>}
            </li>
          ))}
        </ul>
      ) : (
        <p>No posts found.</p>
      )}
    </div>
  );
}

解釋：
- 我們首先導入 GhostContentAPI SDK。
- 使用從 .env.local 讀取的環境變數來初始化 API 客戶端。
- getStaticProps 是 Next.js 的一個特殊函數，它會在伺服器端（建構時）運行，用於獲取頁面所需的數據。這對於 SEO 和效能非常有益（產生靜態 HTML）。
- api.posts.browse() 是 SDK 提供的方法，用於獲取文章列表。您可以傳遞參數來過濾、排序或指定包含的關聯數據（如 tags, authors）。
- 獲取的 posts 數據透過 props 傳遞給 Home 頁面元件。
- Home 元件接收 posts prop 並使用 .map() 方法來渲染文章標題列表。
- revalidate: 60 啟用了 ISR，Vercel 會在背景每 60 秒檢查一次是否有新內容，如果有的話會重新生成頁面，這樣無需每次都手動部署也能更新內容。
運行本地開發伺服器進行測試：
```
npm run dev
# 或
# yarn dev
```
打開瀏覽器訪問 http://localhost:3000，您應該能看到從您的 Ghost 網站獲取的最新文章列表。

步驟四：部署到 Vercel

一旦您的前端應用程式能夠成功連接 Ghost API 並在本地運行，就可以將其部署到 Vercel。

將您的程式碼推送到 Git 倉庫：
- 確保您的 Next.js 專案是一個 Git 倉庫。如果不是，請運行 git init。
- 將您的程式碼提交到 GitHub、GitLab 或 Bitbucket。這是 Vercel 導入專案的首選方式。
```
git add .
git commit -m "Initial commit with Ghost CMS integration"
git remote add origin YOUR_GIT_REPOSITORY_URL
git push -u origin main # 或 master
```
在 Vercel 上導入專案：
- 登入您的 Vercel 帳戶。如果您沒有帳戶，可以免費註冊。
- 在儀表板上，點擊 “Add New…” → “Project”。
- 選擇 “Continue with Git”。選擇您的 Git 提供商（GitHub, GitLab, Bitbucket）並授權 Vercel 訪問您的倉庫。
- 從列表中選擇您剛剛推送的前端專案倉庫。點擊 “Import”。
配置專案設定：
- Project Name：Vercel 會自動使用您的倉庫名稱，您可以修改它。
- Framework Preset：Vercel 通常會自動檢測到 Next.js 並應用最佳設定。無需更改。
- Root Directory：如果您的程式碼不在倉庫根目錄，請指定正確的路徑。通常保持預設即可。
- Build and Output Settings：通常也無需更改 Next.js 的預設值。
- Environment Variables (關鍵步驟)：
  - 展開 “Environment Variables” 部分。
  - 在這裡，您必須添加您在 .env.local 中使用的相同環境變數。這是 Vercel 伺服器在建構和運行時獲取 API 金鑰和 URL 的方式。
  - 添加第一個變數：
    - Name: NEXT_PUBLIC_GHOST_API_URL
    - Value: 貼上您的 Ghost API URL
  - 點擊 “Add”。
  - 添加第二個變數：
    - Name: NEXT_PUBLIC_GHOST_CONTENT_API_KEY
    - Value: 貼上您的 Ghost Content API Key
  - 點擊 “Add”。
  - 確保變數名稱與您在程式碼中 process.env 使用的名稱完全匹配。
部署：
- 點擊 “Deploy” 按鈕。
- Vercel 將從您的 Git 倉庫拉取程式碼，執行建構過程（運行 npm run build 或 yarn build，這會觸發 getStaticProps 來獲取內容），然後將結果部署到其全球 CDN。
- 您可以在 Vercel 儀表板上看到實時的建構日誌。
訪問您的網站：部署成功後，Vercel 會提供一個預覽 URL（類似 your-project-name-abc.vercel.app）。點擊該 URL，您應該能看到部署在 Vercel 上的、由 Headless Ghost CMS 驅動的前端網站。您可以將自訂網域指向這個部署。

步驟五：設定 Webhooks 以自動更新內容 (推薦)

由於我們使用了 getStaticProps (SSG)，Vercel 在建構時會生成靜態頁面。如果您在 Ghost 中發布或更新了文章，Vercel 上的網站不會立即自動更新（除非您使用了 ISR 且緩存過期）。為了在內容更改時立即觸發 Vercel 重新建構和部署，您應該使用 Webhooks。

在 Vercel 中建立 Deploy Hook：
- 進入您在 Vercel 上的專案。
- 前往 “Settings” → “Git”。
- 向下滾動到 “Deploy Hooks” 部分。
- 為您的 Hook 命名（例如 ghost-content-update）。
- 選擇您希望此 Hook 觸發部署的 Git 分支（通常是 main 或 master）。
- 點擊 “Create Hook”。
- Vercel 會生成一個唯一的 URL。複製此 URL。
在 Ghost 中添加 Webhook：
- 返回您的 Ghost 管理後台。
- 前往 “Settings” → “Integrations”。
- 向下滾動到 “Webhooks” 部分。
- 點擊 “Add webhook”。
- 為 Webhook 命名（例如 “Vercel Deploy”）。
- Event：選擇觸發此 Webhook 的事件。對於內容更新，您至少應該選擇：
  - Post published
  - Post updated
  - Page published
  - Page updated
    （您可以根據需要選擇更多事件）
- Target URL：貼上您從 Vercel 複製的 Deploy Hook URL。
- 點擊 “Create”。

現在，每當您在 Ghost 中執行選定的操作（例如發布新文章），Ghost 就會向 Vercel 的 Deploy Hook URL 發送一個請求，這將觸發 Vercel 開始新的建構和部署過程，從而更新您網站上的內容。

總結

透過以上步驟，您已經成功地設定了 Headless Ghost CMS，建立了一個 Next.js 前端來消費其 Content API，並將該前端部署到了高效能的 Vercel 平台。藉由環境變數管理敏感資訊，並利用 Webhooks 實現內容的自動更新，您可以享受到 Headless CMS 的靈活性和 Vercel 的部署便利性與效能優勢。

在 Tenten.co，我們專精於打造高效能、可擴展的 Headless CMS 數位解決方案。無論是複雜的 CMS 整合、客製化前端開發，或是雲端架構優化，我們的團隊都能提供專業支援。如果您在實施 Headless Ghost 方案或任何其他數位專案時需要協助，我們樂意為您服務。

想深入了解我們如何能協助您的業務成長嗎？立即預約一次免費的諮詢會議，與我們的專家交流：預約免費會議