[ 02 / 02 ]·HONGSHAING

約 2 分鐘閱讀

網站框架設計

為什麼選 Headless Shopify、Sanity CMS 的整合方式,以及交易安全與海外市場策略細節。

商務

Shopify

商品 / 變體 / 價格 / 庫存
訂單 / 會員 / 結帳

前端
TanStack Start

內容

Sanity

商品文案 / 品牌故事 / SEO
圖庫 / 條款 / FAQ

前端讀取時用 shopifyHandle 把兩邊接起來
用 API 把兩邊接起來——兩個真相來源,不可雙寫。

[ 01 / 08 ]·background

專案背景

從去年開始,我就曾建立了一個完全客製化的前後端電商專案,不過為了與維護成本取得平衡,我著手重新設計系統架構並進行責任劃分。面對即將擴展的海外市場,若繼續採用全自建模式,多國語系、多幣別、跨境稅務與在地支付等客製邏輯將使維護負擔成倍成長。因此,此重構的核心目標在於明確邊界——將獨特的使用者體驗留給品牌前端自主掌握,將複雜且標準化的商務基礎設施交由成熟平台代勞。

[ 02 / 08 ]·decision

專案目標

為了兼顧前端設計的高自由度與極致效能,同時保有後端服務的彈性,我選擇以 Headless 架構整合 Shopify。Shopify 的國際信任度高,利於未來擴展海外市場;針對台灣在地化需求,則能透過綠界官方 Plugin 快速串接金流。此外,Shopify 提供完整的 API 支援,可完美搭配現代前端框架獨立開發。


要達成什麼?

  1. 01

    保留既有品牌前端

    版面、動效與內容呈現自己掌握

  2. 02

    台灣要能出貨

    金流、物流、發票、會員、售後

  3. 03

    商務交給專業系統

    商品變體、價格、庫存、訂單

  4. 04

    能擴展海外市場

    付款、稅務、物流與在地內容,用設定開通

哪個方案做得到?

市面上能達成商務需求的做法有三種。把上面 01–04 當成同一把尺,逐一量過去。

方案

01

02

03

04

判斷

Shopify theme

商務都到位,但前端被 theme 綁住

延續自建

自由度換來持續累加的維護責任

Headless Shopify

採用

四個條件都達成

四個條件由上而下貫穿:先定義,再逐一對三個方案打分。實心=做得到,空心=做不到。

[ 03 / 08 ]·architecture

架構分工

Shopify

商務

  • 商品・變體・庫存
  • 購物車
  • 訂單・結帳
  • 會員
  • 金流・物流
  • 多幣別・稅務
  • 商品翻譯

Storefront API Customer Account API

TanStack Start

前端

  • 品牌視覺頁面結構、動線完全自訂,不受主題限制
  • 效能SSR、快取、圖片策略自己決定
  • SEO多語系網址、301 規則自己掌握

Sanity API

Sanity

內容

  • 商品文案
  • 品牌故事
  • 規格與相容性
  • FAQ
  • 圖庫
  • 條款
  • SEO 文案
前端在中間組合兩邊的資料:Shopify 管商務,Sanity 管內容。
01
請求商品頁
/zh-tw/products/<handle>
02
Shopify 讀商務
變體 / 價格 / 庫存 @inContext 回翻譯
03
Sanity 讀內容
文案 / 圖庫 / SEO 用同一個 handle 查
04
伺服器端合併
兩邊接起來 token 不進瀏覽器
05
SSR 回頁面
完整 HTML 可被索引
商品頁怎麼組出來。
  • TanStack Start
  • React
  • TypeScript
  • Tailwind CSS
  • Railway
  • Shopify Storefront API
  • Shopify Customer Account API
  • GraphQL
  • Sanity
技術棧。

[ 04 / 08 ]·commerce

交易安全

headless 前端 · TanStack Start

瀏覽商品購物車登入按鈕訂單管理

Storefront API

產品與變體資料

Storefront API

變體 id 與數量 購物車本體存在 Shopify

Customer Account API

登入請求

Customer Account API

訂單、退貨、取消

Shopify 託管頁

結帳付款
OTP 登入

checkoutUrl 導轉

託管結帳頁 金額由 Shopify 重算

託管登入頁

OTP 驗證 憑證不經本站

Shopify 後端

Shopify

商品 · 庫存 · 購物車 · 結帳 · 顧客 · 訂單

三層動線:前端負責瀏覽、購物車與訂單管理,付款與 OTP 登入在 Shopify 託管頁,資料一律回到 Shopify 後端。
環節誰負責怎麼保護
瀏覽、選規格、購物車本站前端只送商品變體 id 與數量
結帳付款Shopify 託管頁售價、折扣與可售狀態由 Shopify 重新計算
登入Shopify 託管頁憑證不經本站,本站不存密碼
訂單查詢、退貨、取消本站透過 Customer Account API 讀取後渲染
私有 token伺服器端發布前掃 client bundle,外洩就擋下

前端只送變體 ID 與數量,金額由 Shopify 在結帳時重算;信用卡與密碼只在託管頁輸入。私有 Token 留於伺服器端。

[ 05 / 08 ]·discovery

海外市場

headless 前端

/zh-tw · /en-tw · 同一份程式碼

Shopify

商品 · 訂單 · 會員 · 結帳 · 兩個市場共用

台灣市場

海外市場

金流

綠界 ECPay

Shopify 官方 App

PayPal · Shop Pay

Shopify 內建

物流

自行指定物流商

訂單填單號與查詢網址

國際快遞

分區運費規則 · 同一套訂單管理

語系 · 偵測國家

/zh-tw

TWD

/en-tw

依偵測國家切換幣別

前端與 Shopify 兩個市場共用,開新市場只換最底下的市場設定。

開海外市場,換幣別只是其中一件事。顧客還要能用自己的語言找到商品、確認規格相不相容、看懂運送與退換規則,最後用當地能用的付款方式結帳。新增市場時,前端和 Shopify 商務核心也能直接沿用,再加上市場設定、付款、稅務、物流與在地內容。

[ 06 / 08 ]·execution

遷移上線

  1. 0108/20平台轉換
    那天要解決的問題
    換到 Shopify 之後,原本的網站外觀還留得住嗎?
    當天做完的
    新站架起來,商品、規格與價格從 Shopify 讀進網站
  2. 0208/21資料來源
    那天要解決的問題
    同一個商品,Shopify 有一份、Sanity 也有一份,以誰為準?
    當天做完的
    價格庫存看 Shopify、介紹圖文看 Sanity,兩邊用同一組商品代號對起來
  3. 0308/22結帳功能
    那天要解決的問題
    從看商品到付完錢、登入會員,中間會不會斷掉?
    當天做完的
    商品頁、購物車、結帳、會員登入整條走通
  4. 0408/23中英網站
    那天要解決的問題
    中英文各自要有固定網址,Google 才找得到
    當天做完的
    中英文網址分開、翻譯內容接上、基本 SEO 設定完成
  5. 0508/24正式上線
    那天要解決的問題
    換成正式網域與正式金流之後,舊資料跟登入還能用嗎?
    當天做完的
    網域切到新站,金流、登入與既有商品資料都接上
  6. 0608/25售後處理
    那天要解決的問題
    下單後想退貨或取消,是不是還要 email 來回問?
    當天做完的
    站內就能申請退貨、取消還沒出貨的訂單,退換規則同步顯示
六天六個階段,每天先解掉一個會擋住顧客下單的問題。點開看那天處理了什麼。

[ 07 / 08 ]·spec

規格驅動開發

人

決策・寫 spec

資料來源、限制、替代方案、驗收條件

AI

拆任務・實作

從定案的 spec 拆出工作並執行

人

驗收

手動測試:功能、安全、資料都對才發布

  1. 01專案建立選定 headless + Shopify,寫遷移 spec
    人

    決策・寫 spec

    選定 headless + Shopify,寫遷移 spec

    AI

    拆任務・實作

    • 提替代方案給比較
    • 快速建立好專案骨架
    人

    驗收

    確認骨架符合 spec

  2. 02前端遷移指定要保留的畫面與路由
    人

    決策・寫 spec

    指定要保留的畫面與路由

    AI

    拆任務・實作

    • 把先前設計好的前端畫面遷移到新專案
    • 前端 UI/UX 優化
    人

    驗收

    逐頁比對舊站

  3. 03商品資料定資料邊界:Shopify 管商務、Sanity 管內容
    人

    決策・寫 spec

    定資料邊界:Shopify 管商務、Sanity 管內容

    AI

    拆任務・實作

    • 批次把產品資料從舊後端匯入 Shopify
    • 找出 SKU 重複的產品
    • 檢查所有產品頁文案
    人

    驗收

    抽查商品頁與價格庫存

  4. 04API 串接寫 spec:每條 API 的資料來源、限制、驗收條件
    人

    決策・寫 spec

    寫 spec:每條 API 的資料來源、限制、驗收條件

    AI

    拆任務・實作

    • 檢查 spec 是否符合 Shopify API 規範
    • 依 spec 寫 API 串接邏輯
    人

    驗收

    手動跑完整交易流程

  5. 05交易安全定邊界:金額與憑證不經本站
    人

    決策・寫 spec

    定邊界:金額與憑證不經本站

    AI

    拆任務・實作

    審查前後端溝通方式,確保私密資料不會留在瀏覽器

    人

    驗收

    發布前確認 bundle 掃描全過

每個領域都走同一個循環:人決策並寫 spec,AI 拆任務與實作,人驗收。前提不成立就回頭改 spec,不在程式裡繞。

使用 spec-driven 的快速開發方式與 AI Agent 協作,每個階段動工前先寫清楚資料來源、限制、替代方案與驗收條件;實作途中發現前提不成立,就回去改規格,並留下一份接手得了的交接狀態,並且在發佈每項更新前做好手動測試,確認功能可行且安全、資料正確才發佈。

[ 08 / 08 ]·outcome

結果

管理端

ADMIN ONLY

系統

不直接對外

對外開放

OPEN ACCESS

Shopify 託管

Shopify Admin

商品 · 訂單 · 會員 · 金流與市場設定

Shopify 商務核心

Storefront API · Customer Account API

Shopify 託管頁

結帳 · 登入(Shopify CDN)

Storefront API Customer Account API

結帳 · 登入時 跳轉再返回

自部署 · TanStack Start

GitHub

程式碼 repo · push 觸發建置

Railway

建置 · 執行 server · 環境變數與私有 token

www.hs-magic.com

商品頁 · 購物車 · 會員中心 · 訂單與售後

Content API(讀)

Sanity 託管

Sanity Studio

內容編輯 · 圖片與文案

Sanity Content Lake

Content API · 以 shopifyHandle 對照商品

內容不直接對外
由網站讀取後呈現
從程式碼到顧客:三條託管線、三個存取層。虛線框只有管理員能進,粗框是顧客實際造訪的入口,中間的系統不直接對外。

在AI Agent 的協助下,一個禮拜內就完成了後端架構的轉換,且也完全複製了原本的前端設計。商品、訂單、會員與結帳交給 Shopify,內容由 Sanity 維護,三者用 shopifyHandle 對照;商品、購物車、結帳、會員、訂單查詢與售後接成同一條流程。