流程定位

前端部署的風險集中在 build time。後端服務可以在 runtime 讀取設定、檢查資料庫與逐步接流量；前端靜態產物多半在 build 階段就把 route、asset path、環境變數與 feature flag 預先寫入 bundle。CI/CD 的判讀重點因此是「被部署的 artifact 是否就是已驗證的那一份」。

Build 階段負責建立可驗證產物。真實服務裡，npm run dev 成功不代表 production build 能成功；CI 應固定 Node 版本、package manager、lockfile、build command 與必要環境變數，讓 artifact 可以從乾淨環境重建。

Browser test 階段負責驗證使用者實際會看到的頁面。Playwright、visual diff、a11y check 或 smoke test 應盡量對 build 後的靜態站執行，避免 dev server 的 fallback、熱更新或寬鬆路由遮蔽 production 問題。

Preview environment 階段負責把 PR 變成可操作畫面。Preview URL 要能追到 PR、commit 與 workflow run，reviewer 才能把畫面問題回報到正確版本；preview 也要隔離 production 資料與 credential，避免預覽環境變成未受控入口。

Deploy 階段負責把 artifact 放到 hosting 或 CDN。前端部署失敗常出現在 cache policy、SPA fallback、base URL、static route 與 sourcemap 權限；deploy 成功只代表檔案上傳完成，仍需要檢查入口頁、核心路由與 asset 是否能從公開網址載入。

Rollback strategy 階段負責恢復上一份可用靜態產物。前端 rollback 表面上只是切回舊檔案，但若 API schema、build time config 或 CDN cache 已經變動，舊頁面仍可能呼叫不相容的後端，因此 rollback 要搭配 smoke test 與 cache purge。

常見失敗路由

前端 CI 紅燈要先判斷失敗在 build、browser test、preview 還是 production deploy。不同層的修復入口不同；把所有紅燈都當成「重跑 workflow」會掩蓋 artifact 漂移與 cache 問題。

這張表的用途是縮短定位時間。前端部署問題常被誤判成「CDN 壞掉」或「瀏覽器快取」，但更常見的根因是 build artifact、route 與 cache policy 的契約沒有明確寫進 pipeline。

最小 workflow 骨架

前端 workflow 應把 build、test、preview 與 deploy 的資料流顯性化。下面是概念骨架，重點在 artifact handoff 的方向，特定平台語法是次要的。

 1jobs:
 2  build:
 3    steps:
 4      - run: npm ci
 5      - run: npm run build
 6      - uses: actions/upload-artifact
 7        with:
 8          name: web-dist
 9          path: dist
10
11  test:
12    needs: build
13    steps:
14      - uses: actions/download-artifact
15        with:
16          name: web-dist
17      - run: npm run test:e2e:static
18
19  preview:
20    needs: test
21    if: github.event_name == 'pull_request'
22    steps:
23      - uses: actions/download-artifact
24        with:
25          name: web-dist
26      - run: npm run deploy:preview
27
28  deploy:
29    needs: test
30    if: github.ref == 'refs/heads/main'
31    steps:
32      - uses: actions/download-artifact
33        with:
34          name: web-dist
35      - run: npm run deploy:production

這個骨架讓 deploy 依賴 test，也讓 test 與 deploy 使用 build job 產生的同一份產物。若專案需要在不同環境注入設定，要明確區分 build time config 與 runtime config，避免同一份 artifact 被重新 build 成另一份內容。

Tripwire

Tripwire 的責任是提醒前端 workflow 需要重切。當同一類問題反覆出現，局部補命令通常只能暫時遮住資料流錯位。

• Preview 常和 production 不一致：把 preview 改成部署 build artifact，讓 preview job 沿用同一份產物。
• E2E 測試通過但 production 壞：把 E2E 改到 static artifact 或 production-like server 上執行。
• rollback 依賴人工找舊 commit：保留 release artifact 與版本索引，讓回退指向明確產物。
• CDN cache 問題反覆出現：把 HTML cache、asset cache 與 purge 策略寫進 deploy checklist。

下一步路由

• 前端部署總覽：回 前端部署 CI/CD。
• Gate 原理：讀 CI gate 與 workflow 邊界。
• 本 blog 靜態站案例：讀 本 blog 專案部署。

點擊/觸碰感測器

點擊感測器偵測使用者和 UI 元素的互動 — 按鈕點擊、連結觸碰、選單選擇。每次互動產生一個 event 類型的事件。

哪些元素值得追蹤

追蹤粒度的判斷依據是「這個互動是否對應一個有意義的使用者意圖」。

有意義的互動（值得追蹤）：提交表單、點擊導航按鈕、觸發功能操作（連線、配對、匯出）。這些互動對應使用者的明確意圖，是 funnel 分析 的步驟候選。

低價值的互動（通常不追蹤）：滾動、hover、重複的相同操作（每秒多次的按鈕連按）。這些互動要麼太頻繁（滾動每秒觸發數十次），要麼不代表新的使用者意圖。

實作方式

Web（JS/TS）：在 document 層級用 event delegation 攔截 click 事件，過濾出帶 data-track attribute 的元素。開發者在需要追蹤的元素上加 data-track="connect-button"，感測器自動收集。不追蹤所有 click — 只追蹤被標記的。

Flutter：用 NavigatorObserver 或 custom GestureDetector wrapper。GestureDetector 包裝在需要追蹤的 widget 外層，onTap 觸發時送出事件。

效能影響

Event delegation 在 document 層級只有一個 listener，效能影響接近零。瓶頸在事件產生頻率 — 如果追蹤了高頻操作（每秒多次的滑動），事件進入 buffer 的速度可能超過 flush 的速度。用取樣控制（見本章末段）。

導航/路由感測器

導航感測器偵測使用者在不同畫面之間的切換 — page view、screen view、route change。每次切換產生一個 lifecycle 類型的事件。

平台差異

Web SPA：SPA 的 route 變換不觸發頁面載入，需要主動偵測 URL 變化。兩種偵測方式：

• History API 攔截：覆寫 pushState / replaceState，攔截 popstate 事件
• 框架層級 Hook：React Router 的 useLocation、Vue Router 的 afterEach guard

History API 攔截是 SDK 層的通用做法（不依賴框架）；框架 Hook 更精確但需要使用者整合（見 JS/TS 平台 的 SPA 路由段）。

Flutter：用 NavigatorObserver 的 didPush / didPop / didReplace 回呼。每次路由變化自動觸發，不需要使用者在每個頁面手動埋點。

Python CLI/Hook：沒有「畫面切換」的概念。對應的 lifecycle 事件是 hook.start / hook.complete — 每個 Hook 執行視為一個「畫面」。

事件 schema

1{
2  "type": "lifecycle",
3  "name": "screen.view",
4  "data": {
5    "screen_name": "TerminalScreen",
6    "previous_screen": "HomeScreen",
7    "navigation_method": "push"
8  }
9}

navigation_method（push / pop / replace / go）記錄導航方式，和 go vs push 的 UX 語意 對應。

錯誤邊界感測器

錯誤邊界感測器攔截元件級的 error — 和 auto-intercept 的全域 error 攔截互補。

和 auto-intercept 的職責分工

全域攔截捕獲「逃逸到頂層的 error」，錯誤邊界捕獲「在元件層級就被攔住的 error」。如果一個 error 被元件的 ErrorBoundary 捕獲，它不會觸發 window.onerror — auto-intercept 看不到它。錯誤邊界感測器填補這個缺口。

實作方式

React：ErrorBoundary 元件的 componentDidCatch 回呼中呼叫 monitor.error()。

Flutter：在 Widget 層用 ErrorWidget.builder 或自訂的 error handling widget。

額外 context

錯誤邊界感測器比全域攔截多一個 context — 知道 error 發生在哪個元件（component name / widget name）。這個資訊在 error 的 data schema 中記錄為 component 欄位。

效能標記感測器

效能標記感測器量測操作的延遲和系統的渲染表現。產生 metric 類型的事件。

Web Core Vitals

Web 平台用 PerformanceObserver API 自動收集三個核心指標：

• LCP（Largest Contentful Paint）：最大內容元素的載入時間
• FID（First Input Delay）：首次互動的延遲
• CLS（Cumulative Layout Shift）：累計佈局位移分數

1new PerformanceObserver((list) => {
2  for (const entry of list.getEntries()) {
3    monitor.metric(`web.vitals.${entry.entryType}`, {
4      value: entry.startTime || entry.value,
5      url: location.pathname
6    });
7  }
8}).observe({ type: 'largest-contentful-paint', buffered: true });

實務上依 entryType 分別取值（LCP 用 startTime、CLS 用 value、FID 用 processingStart - startTime），上述範例簡化示意。

Flutter frame timing

Flutter 用 SchedulerBinding.addTimingsCallback 偵測掉幀：

 1SchedulerBinding.instance.addTimingsCallback((timings) {
 2  for (final t in timings) {
 3    if (t.totalSpan > const Duration(milliseconds: 16)) {
 4      monitor.metric('render.frame_drop', {
 5        'build_ms': t.buildDuration.inMilliseconds,
 6        'raster_ms': t.rasterDuration.inMilliseconds,
 7      });
 8    }
 9  }
10});

16ms 是 60fps 的單幀預算。超過代表掉幀。

自訂 duration 量測

業務操作的延遲用手動標記量測：

1final stopwatch = Stopwatch()..start();
2await connectToTerminal();
3stopwatch.stop();
4monitor.metric('terminal.connect.duration', {
5  'duration_ms': stopwatch.elapsedMilliseconds,
6});

輸入敏感度感測器

輸入敏感度感測器偵測使用者正在輸入敏感資料 — 密碼欄位、API key 輸入、信用卡號碼。這個感測器的責任是觸發 redaction，而非記錄輸入內容。

偵測邏輯

Web：偵測 <input type="password">、帶有 autocomplete="cc-number" 或 data-sensitive attribute 的欄位。當使用者 focus 這些欄位時，標記當前 session 進入「敏感輸入模式」— 後續的事件自動加嚴 redaction 規則（例如暫停記錄按鍵事件）。

Flutter：偵測 TextField 的 obscureText: true 或 enableIMEPersonalizedLearning: false（見 安全敏感輸入框的 IME 控制）。

不記錄的原則

輸入敏感度感測器偵測「使用者正在輸入敏感內容」這個事實，但不記錄輸入的內容本身。送出的事件只包含：

1{
2  "type": "lifecycle",
3  "name": "input.sensitive_mode.entered",
4  "data": { "field_type": "password" }
5}

取樣策略設計

感測器產生的事件量可能很大（效能標記每 30 秒一筆 × 活躍使用者數）。取樣控制事件量、避免 SDK 和 collector 的資源壓力。

三種取樣模式

全收：每筆事件都送出。適合事件量低且每筆都有價值的類型 — error（每筆都可能是新 bug）、lifecycle 狀態轉換（量低）、認證失敗（安全敏感）。

百分比取樣：隨機丟棄一定比例的事件。適合高頻的效能和行為事件。取樣率由 SDK config 控制：

1sensors:
2  metric:
3    render.frame_drop: { sampling: 0.1 }    # 只收 10%
4    resource.memory: { sampling: 0.5 }       # 收 50%
5  event:
6    feature.*.used: { sampling: 1.0 }        # 全收
7    click.*: { sampling: 0.1 }               # 只收 10%

百分比取樣的代價是低機率事件可能被漏掉（取樣 10% 時、發生 5 次的事件可能一次都沒收到）。

條件取樣：正常情況下取樣、特定條件下全收。適合「平時不需要全量但問題發生時需要完整資料」的場景。例：正常 session 取樣 10%、但 session 內發生 error 後、該 session 剩餘事件全收（error session 的完整 context 比正常 session 更有價值）。

取樣率的管理

取樣率可以從三個層級設定：

三個層級由上到下優先順序遞增 — feature flag 覆蓋 collector config、collector config 覆蓋本地 config。

下一步路由

• 動機驅動的事件設計（哪些動機需要哪些感測器） → 動機驅動的事件設計
• 感測器的啟停控制和生命週期 → 感測器生命週期管理
• 被動攔截機制（和感測器互補） → 自動攔截機制
• 安全敏感輸入的完整 checklist → 安全敏感輸入框的 IME 控制

場域定位

前端部署和後端部署的差異在於 runtime 責任位置。前端產物通常在 build time 完成大部分工作，發布後由 browser、CDN 或 static hosting 提供服務；後端服務則要在 runtime 處理連線、資料庫、migration、狀態與 rollback。

Build 階段負責產生 browser 實際會執行的內容。真實服務常見訊號是 bundle size、asset hash、base URL、環境變數與 static route 是否穩定；若 build 只能在開發機成功，CI 就要把 Node 版本、package lock、build command 與環境變數收斂成固定入口。

Test 階段負責驗證使用者可見行為。前端常見測試包含 component test、browser regression、accessibility check 與 layout check；測試應盡量靠近 production artifact，讓 dev server 的寬鬆行為不會蓋掉實際部署問題。

Artifact 階段負責保存可發布產物。靜態檔、搜尋索引與 sourcemap 都可能影響使用者體驗與除錯能力；測試與發布共用同一份 artifact，可以避免「測試通過的是 A，發布出去的是 B」的漂移。

Deploy 階段負責把 artifact 放到 hosting 或 CDN。真實風險通常集中在 HTML cache、asset cache、SPA fallback、preview URL 與 production domain 是否對齊。

Rollback Strategy 階段負責讓上一個可用 artifact 能重新服務使用者。前端 rollback 通常比後端快，但若 build time 環境變數、資料 schema 或 CDN cache 已變更，回退仍需要驗證頁面路由與 API 相容性。

常見注意事項

• CDN cache 要和 asset hash、HTML cache policy 分開看。
• Preview environment 要能對應 PR，讓 reviewer 看到真實 build。
• 前端測試要跑在 production-like artifact 上，避免 dev server 行為遮蔽問題。
• 環境變數若在 build time 注入，重新發布才會生效。
• SPA route 需要 fallback 設定，靜態站 route 需要檔案路徑與 base URL 對齊。

學習路線

下一步路由

• 前端 artifact 流程：讀 前端 artifact 與 preview deployment 流程。
• 本 blog 的靜態站案例：讀 本 blog 專案部署。
• Gate 原理：讀 CI gate 與 workflow 邊界。
• 失敗處理：讀 CI 失敗到修復發布流程。