Astro + Webflow + Shopify 無頭電商整合：透過 GitHub Actions 實現設計自動部署

電商品牌在追求高效能前端的同時，往往面臨設計流程與開發部署之間的斷層。將 Astro.build 作為無頭電商的前端框架、Webflow 作為視覺設計工具，搭配 Shopify Storefront API 處理商務邏輯，再透過 GitHub Actions 串接自動化部署流程，可以建構一套設計師與開發者協作無縫的工作流程。

本文將拆解這套架構的技術實作細節，涵蓋 Webflow DevLink 元件匯出、Astro 專案配置、Shopify API 串接，以及 GitHub Actions 自動化腳本的撰寫。

架構概覽：四層系統的分工

這套整合方案的核心概念在於將網站的不同職責分離到最適合的工具：

這樣的分層讓設計師可以在 Webflow 中自由迭代視覺設計，開發者專注於商務邏輯整合，而部署流程則完全自動化，減少人為錯誤與溝通成本。

第一步：Shopify Storefront API 設定

Shopify 的無頭架構核心是 Storefront API，這是一個 GraphQL API，允許任何前端框架透過 HTTP 請求存取商店資料。

在 Shopify 後台安裝 Headless 銷售管道後，系統會提供 public 與 private access tokens。Private token 用於伺服器端請求，具備完整權限；Public token 則可安全地嵌入前端程式碼。

建立 .env 檔案儲存憑證：

PUBLIC_SHOPIFY_STORE_URL=your-store.myshopify.com
PUBLIC_SHOPIFY_STOREFRONT_TOKEN=your_public_token
SHOPIFY_PRIVATE_TOKEN=your_private_token

API 權限設定建議至少啟用：unauthenticated_read_product_listings、unauthenticated_read_product_inventory、unauthenticated_write_checkouts，這些權限涵蓋產品展示與購物車功能的基本需求。

第二步：Astro 專案初始化與 Shopify 整合

Astro 的 Islands 架構特別適合電商情境——頁面主體為靜態 HTML，僅在需要互動的區塊（購物車、數量選擇器）載入 JavaScript。

使用 astro-shopify 作為起始模板：

git clone https://github.com/thomasKn/astro-shopify.git my-store
cd my-store
pnpm install

此模板已整合 @shopify/hydrogen-react 套件，提供 React 元件來處理購物車狀態管理與結帳流程。Astro 支援 React、Svelte、Vue 等多種框架元件，開發者可依團隊技術棧選擇。

專案結構中，src/utils/shopify.ts 封裝了 GraphQL 請求邏輯，使用 Zod 進行執行時期型別驗證：

import { z } from 'zod';

const ProductSchema = z.object({
  id: z.string(),
  title: z.string(),
  handle: z.string(),
  priceRange: z.object({
    minVariantPrice: z.object({
      amount: z.string(),
      currencyCode: z.string(),
    }),
  }),
});

這確保從 Shopify API 取得的資料符合預期結構，避免前端因資料格式錯誤而崩潰。

第三步：Webflow DevLink 元件匯出

Webflow DevLink 是 Webflow 於 2024 年推出的元件匯出功能，讓設計師在 Webflow Designer 中建立的 UI 元件可以匯出為 React 程式碼，直接用於前端專案。

安裝 Webflow CLI：

npm install -D @webflow/webflow-cli

執行認證流程，CLI 會自動建立 .env 檔案存放 API token：

webflow auth login

建立設定檔 webflow.json：

{
  "devlink": {
    "host": "https://api.webflow.com",
    "rootDir": "./src/devlink",
    "cssModules": true,
    "relativeHrefRoot": "/"
  }
}

在 Webflow Designer 中，將設計元素轉換為 Component，然後執行同步指令：

webflow devlink sync

CLI 會在 src/devlink 目錄生成：React 元件檔案、CSS Modules 樣式檔、全域樣式、DevLinkProvider 互動處理元件。

由於 Astro 原生支援 React 元件，這些匯出的元件可以直接引入使用：

---
import { ProductCard } from '@/devlink/ProductCard';
import { fetchProducts } from '@/utils/shopify';

const products = await fetchProducts();
---

<div class="product-grid">
  {products.map((product) => (
    <ProductCard 
      client:visible
      title={product.title}
      price={product.priceRange.minVariantPrice.amount}
      image={product.featuredImage?.url}
    />
  ))}
</div>

client:visible 指令告訴 Astro 在元件進入視窗後才載入 JavaScript，這是 Islands 架構的關鍵優化手法。

第四步：GitHub Actions 自動化部署

整合的關鍵在於建立 Webflow 設計變更到前端部署的自動化流程。這需要兩個觸發點：Webflow Webhook 與 GitHub Actions workflow。

Webflow 支援 site_publish webhook，當設計師在 Webflow 發布網站時觸發。透過 Webflow API 建立 webhook：

curl -X POST "https://api.webflow.com/sites/YOUR_SITE_ID/webhooks" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "triggerType": "site_publish",
    "url": "https://api.github.com/repos/YOUR_ORG/YOUR_REPO/dispatches"
  }'

GitHub Actions 的 repository_dispatch 事件可接收外部 webhook 觸發。建立 .github/workflows/sync-webflow.yml：

name: Sync Webflow Components

on:
  repository_dispatch:
    types: [webflow-publish]
  workflow_dispatch: # 手動觸發選項

jobs:
  sync-and-deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'
          
      - name: Install dependencies
        run: pnpm install
        
      - name: Sync Webflow components
        env:
          WEBFLOW_API_TOKEN: ${{ secrets.WEBFLOW_API_TOKEN }}
        run: npx webflow devlink sync
        
      - name: Build Astro site
        env:
          PUBLIC_SHOPIFY_STORE_URL: ${{ secrets.SHOPIFY_STORE_URL }}
          PUBLIC_SHOPIFY_STOREFRONT_TOKEN: ${{ secrets.SHOPIFY_TOKEN }}
        run: pnpm build
        
      - name: Deploy to Vercel
        uses: amondnet/vercel-action@v25
        with:
          vercel-token: ${{ secrets.VERCEL_TOKEN }}
          vercel-org-id: ${{ secrets.VERCEL_ORG_ID }}
          vercel-project-id: ${{ secrets.VERCEL_PROJECT_ID }}
          vercel-args: '--prod'

這個 workflow 會在接收到 Webflow 發布事件後，自動同步最新元件、重新建構 Astro 網站，並部署至 Vercel。整個流程約需 2-4 分鐘。

若需要更精細的控制，可以加入中介服務（如 n8n 或 Make）來處理 webhook 轉發與條件判斷，例如僅在特定頁面變更時才觸發部署。

效能考量與最佳實踐

這套架構的效能優勢來自多個層面：

Astro 的靜態生成確保頁面載入時無需等待 JavaScript bundle，首次內容繪製（FCP）可達 1 秒以內。根據 astro-shopify 專案的 Lighthouse 測試，四項指標均可達到 90 分以上。

DevLink 匯出的 CSS Modules 避免全域樣式衝突，每個元件的樣式獨立封裝。搭配 Astro 的自動 CSS 內聯，關鍵渲染路徑不會被外部樣式表阻塞。

Shopify Storefront API 的 GraphQL 特性允許精確查詢所需欄位，避免過度載入資料。對於產品清單頁面，僅查詢標題、價格、縮圖即可，完整產品資訊留待產品頁面再載入。

對於需要額外加速的場景，可整合 Cloudflare 快取策略，在邊緣節點快取 API 回應，進一步降低延遲。

常見問題與解決方案

DevLink 元件在 Astro 中樣式失效，通常是因為未正確匯入全域樣式。需在 src/layouts/BaseLayout.astro 加入：

---
import '@/devlink/global.css';
import { DevLinkProvider } from '@/devlink/DevLinkProvider';
---

Shopify API 回傳 401 錯誤，檢查是否使用了正確的 API 類型。Storefront API 與 Admin API 的端點與權限完全不同，前者用於公開前端，後者用於後台管理。

GitHub Actions 無法觸發，確認 webhook URL 格式正確，且 GitHub Personal Access Token 具備 repo 權限。webhook 請求需包含 event_type 欄位：

{
  "event_type": "webflow-publish",
  "client_payload": {
    "site_id": "..."
  }
}

延伸應用：無頭 CMS 整合

這套架構可進一步擴展，將內容管理從 Shopify 抽離到專門的 Headless CMS。Webflow 本身的 CMS 功能可透過 API 存取，或整合 Sanity、Contentful 等服務，實現產品資料與行銷內容的分離管理。

Astro 的 Content Collections 功能可統一處理多來源內容，無論是 Markdown 檔案、CMS API，或 Shopify 產品資料，都能以一致的方式查詢與渲染。

結語

將 Webflow 的視覺設計能力、Astro 的靜態效能優勢、Shopify 的成熟電商功能，透過 GitHub Actions 串接成自動化流程，解決了傳統電商開發中設計與開發脫節的問題。設計師的每次發布都能自動反映在生產環境，開發者則專注於商務邏輯與效能優化，兩者各司其職，效率最大化。

這套方案特別適合需要高度客製化前端體驗、同時維持快速迭代能力的品牌電商。技術複雜度雖高於傳統 Shopify 主題開發，但換來的是完全的設計自由度與極致的載入效能。

引用來源

• Shopify Storefront API Documentation - Shopify 官方開發者文件
• Webflow DevLink Quick Start - Webflow 開發者文件
• Astro Islands Architecture - Astro 官方文件
• GitHub Actions Workflow Triggers - GitHub 官方文件

作者

Ewan Mak - Tenten 全端開發者

專注於現代網頁應用開發，擅長 Headless CMS、Vercel 與 Cloudflare 部署優化。在電商領域，Ewan 認為無頭架構不只是技術選擇，更是品牌掌控顧客體驗的策略決定。當設計與開發的界線模糊，創新的空間才真正打開。

若您正在評估無頭電商架構，或希望提升現有 Shopify 商店的前端效能，歡迎與 Tenten 團隊預約諮詢，討論最適合您品牌的技術方案。