Flutter

前言：手動維護 53 種食物的極限 我正在開發一款健康追蹤 App，核心功能之一是飲食記錄。一開始，食物資料庫是手動維護的 JSON — 53 種台灣常見小吃，從滷肉飯到珍珠奶茶。 53 種夠用嗎？使用者搜尋「鮭魚」找不到、搜尋「優格」找不到、搜尋「oatmeal」更不用說。手動新增不可能跟上需求，我需要一條自動化管線，把全世界的食物營養資料拉進來。 這就是 ETL 管線登場的時機。 什麼是 ETL？用食物資料庫解釋 ETL 是 Extract（擷取）、Transform（轉換）、Load（載入） 的縮寫，是資料工程最基礎的設計模式。與其抽象解釋，直接用這個專案的食物資料庫來看： 四個來源的原始資料格式完全不同 — 台灣用中文欄位名（粗蛋白）、日本用 FAO 代碼（prot）、USDA 用數字編號（203）。Transform 階段把它們統一成 App 需要的 {id, name, emoji, category, nutrition} 結構。 為什麼不直接在 App 端串接 API？因為食物營養資料是靜態的 — 雞蛋的蛋白質含量不會每天變。離線 JSON 零延遲、不吃流量、無網路也能用。ETL 只在開發階段跑一次，產出的 JSON 跟著 App 一起發布。 USDA API 的格式陷阱：同一個服務，兩套規則 USDA FoodData Central 是美國農業部的食物營養資料庫，涵蓋近 8,000 種食物。我選擇 foods/list endpoint 批量下載 SR Legacy 和 Foundation Foods 資料。 然而，這個 API 有一個文件沒有明確說明的陷阱：foods/list 和 foods/search 兩個 endpoint 回傳的營養素格式完全不同。 ...

那個怎麼都消不掉的警告 Google Play Console 上掛著一則警告：「App Bundle 含有原生程式碼，而您尚未上傳偵錯符號檔」。 先釐清幾個名詞，因為 Google Play 的警告訊息把不同的東西混在一起講： 檔案 用途 來源 Native Debug Symbols (.so) 還原 C/C++ native crash 的堆疊追蹤 Flutter 引擎、NDK、第三方 SDK R8 Mapping (mapping.txt) 還原 Java/Kotlin 被 R8 混淆後的類別名稱 Gradle build（minifyEnabled true） 兩者都要上傳，Google Play 才不會抱怨。Flutter 專案兩者都需要：引擎帶了 .so，Gradle 開了 R8。 整體流程：Build → Detect → Upload 在看個別陷阱前，先理解正確的 CI 流程應該長什麼樣： 關鍵原則：上傳邏輯綁定 build 產物，不綁定部署環境。只要 build 裡有 .so 或 mapping.txt，就上傳。不管是 staging 還是 production。 但從這個目標到實際跑通，踩了三個完全不同性質的坑。 陷阱一：File.expand_path 的基準不是你以為的那個 第一版的 Fastfile 寫死了路徑： ...

結帳頁突然報錯：Missing or invalid credentials 使用者在 App 內開啟網頁版結帳頁，輸入折扣碼後收到一個刺眼的錯誤訊息：「Missing or invalid credentials」。 不是每個人都遇到，也不是每次都發生。但只要在頁面上停留超過一段時間再操作，就一定會觸發。 聽起來很熟悉？沒錯，這跟前一篇文章的問題同源——JWT 15 分鐘過期。差別在於，上次是後端的 refresh API 被權限系統擋掉，這次是前端根本沒有呼叫 refresh 的能力。 架構背景：App 開網頁的 SSO 流程 我們的 Flutter App 會透過 in-app browser 開啟 Vue 網頁。token 的傳遞方式很直接： https://web.example.com/checkout/xxx?token=eyJhbG... Vue 從 URL query param 取得 JWT，存進 sessionStorage，之後的 API 呼叫都帶這個 token。 問題在於：只傳了 JWT，沒有傳 refresh token。 JWT 有 15 分鐘的壽命。使用者開啟頁面、慢慢填寫發票資料、比較方案——15 分鐘一晃就過了。接下來任何 API 呼叫都會收到 401，但 Vue 手上沒有 refresh token，無法換新的 JWT。只能眼睜睜看著使用者被擋在門外。 為什麼 Flutter 不需要擔心，但 Vue 必須處理 Flutter App 本身有完整的 token refresh 機制：interceptor 攔截 401、用 refresh token 換新 JWT、重送失敗的 request。整個流程無縫，使用者無感。 ...

問題現象：Xcode 正常，冷啟動閃退 最近在開發 Flutter iOS App 時遇到一個詭異的問題：透過 Xcode 按下 Run 按鈕啟動 App 完全正常，但當我停止 Debugger、從多工畫面滑掉 App、再從主畫面點擊圖示重新開啟時，App 只顯示 Launch Screen 就立刻閃退。 這個問題讓我走了不少彎路，最後發現答案簡單得令人意外。 誤導方向：UIScene 與 Plugin 註冊 由於 Xcode 26 開始顯示 UIScene lifecycle will soon be required 警告，我最初懷疑是 UIScene 遷移不完整導致的問題。接著又懷疑是 Plugin 註冊的 race condition，甚至在 GeneratedPluginRegistrant.m 中加入大量 debug log 來追蹤每個 Plugin 的註冊狀態。 嘗試過的「修復」包括： 完整實作 SceneDelegate 與 FlutterSceneDelegate 在 Flutter Engine 初始化前加入 0.5 秒延遲 逐一排除可能有問題的 Plugin 這些方向全部是錯的。 找到根本原因：iOS Console Log 關鍵轉折點是查看 iOS 的 Console log。使用 Xcode 的 Devices and Simulators > Open Console 或 macOS 的 Console.app 連接 iPhone，重現冷啟動閃退後，看到了這段關鍵訊息： ...

前言：當建置一直紅燈 CI/CD pipeline 亮紅燈是開發日常，但連續遇到三個不同層面的問題，從 iOS codesigning、Android Gradle、到 Google Play API，這就值得記錄下來了。 這篇文章記錄我在同一天內遇到的三個建置失敗，以及逐步排除的過程。每個問題都有其獨特的根因，但也反映出 CI/CD 環境的複雜性。 問題一：iOS Keychain 解鎖失敗 症狀 Jenkins 建置在 iOS 階段失敗，錯誤訊息： [!] Error unlocking keychain at path: fastlane_keychain Command failed with exit status 51 macOS Keychain 運作機制 在深入問題之前，先了解 macOS Keychain 的運作方式： 關鍵概念： macOS 可以有多個 Keychain，每個都有獨立密碼 憑證必須在「已解鎖」的 Keychain 中才能被 codesign 使用 CI 環境通常會建立專用的 Keychain，避免影響系統 Keychain Fastlane Match 與 Keychain 的互動流程 調查過程 Exit status 51 代表「密碼錯誤」。SSH 進 Jenkins Mac mini 確認： ...

前言：同一個功能，截然不同的 Debug 體驗 最近在維護一個同時有 Vue 前端和 Flutter App 的專案。兩邊都要實作「關於我們」頁面的選單過濾邏輯——根據不同情境顯示或隱藏特定項目。 Vue 那邊：兩天內改了十幾個 commit，每次都是小幅調整，順順地完成。 Flutter 這邊：卡了一整天，改了一個地方沒效果，懷疑方向錯誤，來回折騰。 同樣的業務邏輯，為什麼 debug 體驗差這麼多？ 這篇文章從 debug 實戰出發，一路延伸到架構層面的反思。我們會探討 Domain Model 的防禦能力、Clean Architecture 的責任邊界、扁平架構的取捨、BFF 的可靠性價值，最後揭露這次 debug 困難的真正原因——交接代碼的信任陷阱。 Part 1：Debug 實戰 Vue：問題在 UI 顯示層 Vue 那邊的典型修正長這樣： // Vue - 在 computed 裡加一個 filter const filteredPageTabs = computed(() => { return response.value.pageTabs .filter(item => item.subtitle !== 'Service') .map(item => { if (item.subtitle === 'ABOUT_US') { return { ...item, subTabs: item.subTabs?.filter( subTab => subTab.title !== '醫療團隊' ) || [] } } return item }) }) 問題本質：資料從 API 回來是正確且完整的，只需要決定「哪些要顯示在畫面上」。 Debug 過程：打開 Vue DevTools → 看 store 資料 → 加個 filter → 完成。整個過程不超過 10 分鐘。 ...

前言：當 Banner 在眾目睽睽下消失 如果你曾經盯著一個「昨天還好好的」功能，然後花了幾小時才發現問題根本不在你想的地方——恭喜你，你已經正式成為資深工程師了。 這次的主角是一個 Flutter App 的首頁輪播 Banner。用戶回報說「Banner 不見了」，而我的第一反應是：「一定是最近的 commit 搞壞的！」 （劇透：不是。） 第一階段：追蹤嫌疑犯 嫌疑人一號：最近的 Git Commit 最近剛好有一個 commit 修改了後端的 middleware，用來處理認證相關的端點。自然而然，我先從這裡開始查： git show abc123 # fix: add middleware to strip auth header for public endpoints 看起來這個 middleware 只處理 /api/auth/forgot-password 這類認證端點，跟 Banner API 完全無關。 結論：無罪釋放。 嫌疑人二號：Strapi 權限設定 接下來檢查 Strapi Admin 的權限設定。Public 角色的 app-home-page 權限： 角色 find 權限 Authenticated ✅ 已開啟 Public ✅ 已開啟 權限設定完全正確。 結論：也不是兇手。 第二階段：真相大白 測試 REST API 直接用 curl 測試 REST API： ...

前言：當 Build Failed 成為日常 在過去的 19 個小時裡，我經歷了 15 次 build failed，產生了 15 個 fix commits。如果你覺得這很誇張，讓我告訴你更誇張的：最後一個 bug 是 git describe 在多個 tag 指向同一 commit 時會隨機返回其中一個。 是的，隨機。在 CI/CD Pipeline 裡。 這篇文章完整記錄這場除錯馬拉松，從最初的 Fastlane 版本問題，到 Discord 通知功能的實作與修復，再到 Ruby 相容性地獄，最後揭開 git 鮮為人知的行為。泡杯咖啡，這會是一段旅程。 第一章：Fastlane 與 Bundler 的糾葛 問題 1：Fastlane 版本不一致 Commit: fix(jenkins): use bundle exec for fastlane to ensure version consistency Jenkins 機器上有全域安裝的 Fastlane，但版本與 Gemfile.lock 指定的不同。這導致某些 action 行為不一致。 // Before: 使用全域 fastlane sh 'fastlane ios build' // After: 透過 Bundler 執行，確保版本一致 sh 'bundle exec fastlane ios build' 學習：在 CI 環境中，永遠使用 bundle exec 執行 Ruby 工具，確保版本與 lockfile 一致。 ...

前言：Flutter 狀態管理的核心挑戰 在 Flutter 開發中，狀態管理是最重要也最複雜的主題之一。當應用程式規模增長，Widget 樹層級加深，如何讓不同層級的 Widget 能夠正確地監聽和響應狀態變化，成為每個 Flutter 開發者必須面對的挑戰。 選擇錯誤的狀態監聽方式，會導致： ❌ 不必要的重繪：整個 Widget 樹被重建，效能下降 ❌ 記憶體洩漏：忘記釋放監聽器，導致記憶體持續增長 ❌ 狀態不同步：多個 Widget 顯示不一致的資料 ❌ 程式碼難以維護：狀態邏輯散落各處，難以追蹤 本文涵蓋內容 本文將深入探討 Flutter 四大主流狀態管理方案的監聽機制： Provider：Flutter 官方推薦的輕量級狀態管理 Bloc：基於 Stream 的企業級狀態管理 Riverpod：Provider 的改進版本，解決了 Provider 的核心問題 GetX：高效能的響應式狀態管理 我們將從實際問題出發，比較這四種方案的： 🔍 核心原理：底層如何實現狀態監聽 💻 實戰範例：可執行的完整程式碼 ⚡ 效能表現：重繪範圍、記憶體使用 🎯 適用場景：什麼情況下使用哪種方案 ⚠️ 常見陷阱：實戰中容易踩的坑 Provider 狀態監聽機制 Provider 是 Flutter 官方推薦的狀態管理方案，基於 InheritedWidget 實現。它的核心優勢是簡單易用，適合中小型應用。 Provider 核心概念 Provider 使用 依賴注入 (Dependency Injection) 和 作用域 (Scope) 的概念來管理狀態： 關鍵概念： Provider 有作用域限制：只有在 Provider 子樹內的 Widget 能存取狀態 三種存取方式：context.watch()、context.read()、context.select() 自動重繪機制：使用 watch 時，狀態改變會自動觸發 Widget 重繪 實戰問題：跨路由讀取 Provider 這是我在開發中遇到的真實問題： ...