[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-1856":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":10,"language":11,"languages":10,"totalLinesOfCode":10,"stars":12,"forks":13,"watchers":14,"openIssues":15,"contributorsCount":16,"subscribersCount":16,"size":16,"stars1d":17,"stars7d":18,"stars30d":19,"stars90d":16,"forks30d":16,"starsTrendScore":20,"compositeScore":21,"rankGlobal":10,"rankLanguage":10,"license":22,"archived":23,"fork":23,"defaultBranch":24,"hasWiki":23,"hasPages":23,"topics":25,"createdAt":10,"pushedAt":10,"updatedAt":38,"readmeContent":39,"aiSummary":40,"trendingCount":16,"starSnapshotCount":16,"syncStatus":41,"lastSyncTime":42,"discoverSource":43},1856,"locwarp","keezxc1223\u002Flocwarp","keezxc1223","iPhone GPS simulator for Windows with USB\u002FWiFi Tunnel, route simulation, joystick control, and dual-device sync.","https:\u002F\u002Fgithub.com\u002Fkeezxc1223\u002Flocwarp",null,"TypeScript",200,40,153,1,0,4,9,38,12,4.84,"MIT License",false,"main",[26,27,28,29,30,31,32,33,34,35,36,37],"fakegps","gps","gps-spoofing","ios","iphone-location","location-simulator","location-spoof","location-spoofing","pikmin-bloom","pokemon-go","pymobiledevice3","windows","2026-06-12 02:00:33","# LocWarp\n\n**iOS 虛擬定位模擬器**, 在 Windows 上控制 iPhone 的 GPS 定位,支援直接跳點、導航、路線循環、多點停留、隨機漫步、搖桿操作等模擬模式,可經由 USB 或 WiFi 連線。\n\n\u003Cp align=\"right\">\n  \u003Ca href=\"README.md\">\u003Cimg alt=\"繁體中文\" src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002F繁體中文-active-2d3748?style=flat-square\">\u003C\u002Fa>\n  \u003Ca href=\"README.en.md\">\u003Cimg alt=\"English\" src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FEnglish-gray?style=flat-square\">\u003C\u002Fa>\n\u003C\u002Fp>\n\n\u003Cp align=\"center\">\n  \u003Ca href=\"https:\u002F\u002Flin.ee\u002FUwdCrmf\" target=\"_blank\">\n    \u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FLINE-加我好友-06C755?style=for-the-badge&logo=line&logoColor=white\" alt=\"LINE\" height=\"40\">\n  \u003C\u002Fa>\n    \n  \u003Ca href=\"#usdt-斗內-trc-20--tron-鏈\" target=\"_blank\">\n    \u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FUSDT-TRC--20-26A17B?style=for-the-badge&logo=tether&logoColor=white\" alt=\"USDT\" height=\"40\">\n  \u003C\u002Fa>\n\u003C\u002Fp>\n\n> 有問題或想聯絡作者, 歡迎[加 LINE](https:\u002F\u002Flin.ee\u002FUwdCrmf)。  \n> 想支持開發者, 可以用下方 USDT 地址直接斗內。\n\n### USDT 斗內 (TRC-20 \u002F TRON 鏈)\n\n**錢包地址**\n\n```\nTB1i7pEcifAeh8oDLLZFqiRVrpUaZmmDAn\n```\n\n**僅支援 TRC-20 (TRON 鏈)**\n\n\u003Cp>\n  \u003Cimg src=\"docs\u002Fdonate-usdt-tron-qr.png\" alt=\"USDT TRC-20 QR\" width=\"260\">\n\u003C\u002Fp>\n\n\n> ### 專案性質聲明\n>\n> LocWarp 為個人獨立維護之開源專案,非商業產品,亦無專職團隊。開發者將盡力於合理時間內新增功能、回應 Issue、修復 Bug 並隨 iOS \u002F pymobiledevice3 版本演進持續更新,然:\n>\n> - 本專案僅保證**於開發者本人測試環境**(目前為 iPhone 16 Pro Max \u002F iOS 26.4.1 + Windows 11 專業版)下運作正常;\n> - **不保證於其他裝置、iOS 修補版本、網路環境、系統配置下皆能穩定使用**;\n> - 若遇到問題,歡迎至 [Issues](https:\u002F\u002Fgithub.com\u002Fkeezxc1223\u002Flocwarp\u002Fissues) 提交完整環境資訊與日誌,以協助定位與改善;\n> - 本專案不保證永續維護,亦不承擔因使用本工具所生之任何責任。\n\n> ### 系統需求\n>\n> **LocWarp 自 v0.1.49 起僅支援 iOS \u002F iPadOS 17 以上的裝置。**\n>\n> iOS 17+ 為主要支援版本(開發者日常測試);**iOS 16.x 自 v0.2.5 起由 @bitifyChen (#9) 社群維護**,走 LegacyLocationService 路徑,最低門檻為 iOS 16.0。iOS 15 以下不受支援。\n\n> ### 相容性測試狀態\n>\n> | 主版本 | 已驗證版本 | 狀態 |\n> | --- | --- | --- |\n> | **iOS 26.x** | 26.4.2 · 26.4.1 · 26.4.1 iPadOS · 26.4 · 26.3.1 · 26.2 · 26.2.1 iPadOS (M1 iPad) | ![Reported](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002F回報可用-6c8cff?style=flat-square) |\n> | **iOS 18.x** | 18.7.8 · 18.7.7 · 18.7.1 · 18.6.2 · 18.5 iPadOS · 18.3.1 · 18.1.1 | ![Reported](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002F回報可用-6c8cff?style=flat-square) |\n> | **iOS 17.x** | 17.6.1 | ![Reported](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002F回報可用-6c8cff?style=flat-square) |\n> | **iOS 16.x**(社群維護) | 16.7.15 · 16.7.12([#9](https:\u002F\u002Fgithub.com\u002Fkeezxc1223\u002Flocwarp\u002Fpull\u002F9),@bitifyChen) | ![Reported](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002F回報可用-6c8cff?style=flat-square) ![Community](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002F社群維護-ffa726?style=flat-square) |\n> | **iOS 15.x 及以下** | n\u002Fa | ![Unsupported](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002F不支援-f44336?style=flat-square) |\n>\n> **說明**:上表僅彙整開發者實測與少數社群回饋的結果,**並不保證於所有相同版本的裝置、網路環境或系統組合下皆能正常運作**。iOS 虛擬定位的穩定性高度依賴 iOS 修補版本、pymobiledevice3 對該版本的支援程度、Developer Disk Image 是否成功掛載,以及 Windows 端的驅動、VPN、防火牆、AV 配置。因此「回報可用」僅代表**至少一位使用者在其特定環境下成功運作**,不等同於通用相容性聲明。\n>\n> 未列於上表的 iOS 16+ 版本並非確定不相容,僅表示尚未收到回報。使用前請自行評估風險,若遇到問題、發現 Bug 或確認某版本可用,歡迎至 [Issues](https:\u002F\u002Fgithub.com\u002Fkeezxc1223\u002Flocwarp\u002Fissues) 提出以協助累積相容性資料。\n\n\u003Cp align=\"center\">\n  \u003Cimg src=\"frontend\u002Fbuild\u002Ficon.png\" width=\"128\" alt=\"LocWarp\">\n\u003C\u002Fp>\n\n\u003Cp align=\"center\">\n  \u003Ca href=\"#使用者端需求\">\n    \u003Cimg alt=\"使用者端說明\" src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002F使用者端說明-2d3748?style=for-the-badge&logo=readthedocs&logoColor=white\">\n  \u003C\u002Fa>\n  \u003Ca href=\"https:\u002F\u002Fgithub.com\u002Fkeezxc1223\u002Flocwarp\u002Freleases\">\n    \u003Cimg alt=\"下載安裝檔\" src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002F下載安裝檔-4285f4?style=for-the-badge&logo=github&logoColor=white\">\n  \u003C\u002Fa>\n\u003C\u002Fp>\n\n\u003Cp align=\"center\">\n  \u003Cimg src=\"docs\u002Fdemo-v2.gif\" width=\"720\" alt=\"LocWarp demo\">\n\u003C\u002Fp>\n\n---\n\n## 功能\n\n### 移動模式\n\n| 模式 | 說明 |\n| --- | --- |\n| **Teleport** | 瞬間跳到指定座標 |\n| **Navigate** | 從目前位置沿 OSRM 路線步行\u002F跑步\u002F開車到目的地 |\n| **Route Loop** | 無限循環指定路線,**每站隨機 5~20 秒停頓**(可自訂) |\n| **Multi-stop** | 依序經過多個停靠點,**每站隨機 5~20 秒停頓**(可自訂) |\n| **Random Walk** | 在指定半徑內隨機漫遊,每段停頓時間可調 |\n| **Joystick** | 以方向 + 力度即時操控,支援 **WASD \u002F 方向鍵** 鍵盤操作 |\n\n#### 點對點跳躍 (v0.2.96+)\n\n路線巡迴 \u002F 多點導航中可勾「**點對點跳躍**」,改成逐點瞬移、每點停留設定的秒數 (預設 12,可手動調整),不再走 OSRM 路徑。適合不想真的走過去、只要 iPhone 依序停留在每個點上的場景。設定會記在 localStorage。\n\n\n### 多裝置群組模式 (v0.2.0+, 三裝置上限)\n\n可同時連接 **最多三台 iPhone**,所有操作 (瞬移、導航、巡迴、多點導航、隨機漫步、搖桿、暫停、繼續、停止、套用速度、全部還原) 會**同步發送**到所有連線的裝置(桌面 UI 跟手機操控都支援)。\n\n- 側邊欄頂端裝置 chip 顯示連線狀態與目前模式;右鍵選單可單獨還原 \u002F 開發者模式 \u002F 中斷該台\n- 底部狀態列多 pill 並陳每台座標、速度、模式;「全部還原」一鍵清除全部虛擬定位\n- **自動同步起點**:啟動任何群組動作前先把所有裝置瞬移到同座標,確保路徑一致\n- **隨機漫步共用亂數種子**:所有裝置目的地序列完全相同,跑幾小時也不會脫鉤\n- **冷卻 toggle 自動鎖定為關閉**:避免裝置同步動作互相阻擋\n- **自動連線**:USB 偵測到新裝置 1 秒內自動配對,直到 3 台上限,第四台插上完全不理\n- 地圖維持單一視覺 (所有裝置已永遠重疊,多 marker 反而是雜訊),裝置狀態靠 chip 與 StatusBar pill 呈現\n\n### 路徑來源選擇 (v0.2.90+ \u002F BRouter v0.2.91+)\n\n模式區塊「使用直線路徑」下方多一顆「**路徑來源**」按鈕,點開彈窗可在四家免費路徑生成服務之間切換(全部免 API key、免註冊、免綁卡):\n\n| 引擎 | Endpoint | 說明 |\n| --- | --- | --- |\n| **OSRM 公用 demo**(預設) | `router.project-osrm.org` | 全球涵蓋,無需金鑰,有時整個服務會掛 |\n| **OSRM FOSSGIS** | `routing.openstreetmap.de` | 同樣是 OSRM 引擎,改由 FOSSGIS 託管的鏡像 |\n| **Valhalla** | `valhalla1.openstreetmap.de` | 完全不同的路徑引擎,當 OSRM 兩個節點都掛時最有用 |\n| **BRouter** | `brouter.de` | 第四個獨立引擎(個人營運多年穩定),OSM 資料 + 自家路徑引擎,涵蓋全球,單車 \u002F 健行 \u002F 開車 profile 齊全 |\n\n選擇記在 localStorage,下次自動套用。任何引擎失敗(502 \u002F timeout \u002F NoRoute)時這一段自動退回密化直線,下一段繼續打引擎,不會卡死。勾「使用直線路徑」時整個選擇器會 disable,因為連引擎都不打。\n\n### 速度控制\n\n- **預設三檔**:走路 5 \u002F 跑步 10 \u002F 開車 40 km\u002Fh\n- **自訂固定速度**:輸入任意 km\u002Fh 覆蓋模式預設\n- **隨機範圍**:輸入 min ~ max(例如 40 ~ 80 km\u002Fh),後端每段路重抽,模擬真實路況\n- **路線中即時套用新速度**:導航 \u002F 巡迴 \u002F 多點 \u002F 隨機漫步 \u002F 搖桿模式進行中可修改速度後按「**套用新速度**」,後端從當前位置以新速度重算剩餘路段並接續執行,**不需停下重來**\n- 狀態列顯示**後端實際生效**的速度(輸入新值未套用前不會誤顯示)\n- 到點\u002F到圈暫停時,地圖上方顯示橘色倒數橫幅\n\n### 手機網頁操控 (v0.2.96+)\n\n不在電腦旁也能用手機操控 LocWarp。底部狀態列「**手機操控**」按鈕跳出 modal 顯示 LAN 內網址跟 6 位數 PIN,把網址打到手機瀏覽器、輸入 PIN,手機就拿到一張行動裝置版的地圖加七顆功能鈕:\n\n> **使用前提**:手機必須先連上跟電腦**同一個 WiFi 網路**(只用行動數據抓不到電腦的內網 IP),電腦防火牆若擋 8777 port 也要先放行。電腦端對 iPhone 的連線方式 (USB 或 WiFi Tunnel) 不限,有任何一種能控到 iPhone 即可。\n\n| 功能 | 行為 |\n| --- | --- |\n| **瞬移** | 點地圖任一點瞬移過去 |\n| **導航到這裡** | 從目前虛擬位置走過去,可選走路 \u002F 腳踏車 \u002F 開車或自訂 km\u002Fh |\n| **搜尋地址** | 輸入地名查 Nominatim,點結果直接瞬移 |\n| **座標飛** | 一行輸入框自動掃出有效座標 (跟桌面版同一個 parser) |\n| **停止 \u002F 還原** | 跟桌面版同邏輯 |\n\n- 手機端地圖即時顯示桌面同一條藍色路徑線 (HTTP polling)\n- Token 隨機 32-hex,只在桌面 modal 取得;PIN 6 位數,輸錯 401 拒絕\n- 「重新產生」可立刻換一組 PIN + token,讓之前配對過的手機失效\n\n### 連線方式(iOS 16+)\n\n- **USB 有線**:插上即自動連線,鎖屏不影響\n- **WiFi Tunnel(USB 拔除模式)**:\n  - 按「自動偵測」→ 先 mDNS 廣播 → 失敗自動退回 \u002F24 TCP 掃描 port 49152\n  - 成功連線的 IP \u002F Port 記到 localStorage,下次自動預填\n  - 停止 Tunnel 後若 USB 仍插著,**自動切回 USB 模式**\n  - 「**重新配對**」按鈕:RemotePairing 記錄損毀時可一鍵透過 USB 重建 `~\u002F.pymobiledevice3\u002F`(iPhone 會跳信任提示)\n- **USB 即時熱插拔偵測**:\n  - 拔除 USB 約 4 秒內偵測,清除 engine + 廣播紅色橫幅 + 右鍵選單顯示「USB 已斷開」\n  - 重新插上自動偵測 + 重新連線 + 重建 engine,**不必重新整理**\n- **連線時版本檢查**:iOS \u003C16 直接拒絕並顯示具體版本與升級提示\n\n### Developer Disk Image\n\n- iOS 17+ 需要 **Personalized DDI** 掛在 iPhone 上才能走 DVT(instruments → dtservicehub)\n- v0.2.58 起 LocWarp **不自動下載、不自動掛載 DDI**(iOS 26.4.1 的 RSD tunnel 撐不住 20MB 上傳導致不穩);改為只檢查 iPhone 上是否已有 DDI,沒有就跳提示請先在 iPhone 上掛過一次 DDI 後再回來使用(掛載工具參考下方[疑難排解](#疑難排解)章節)\n\n### 地圖與輔助\n\n- **地圖定位按鈕**(左上角):一鍵置中目前虛擬位置\n- **圖層切換**(右上角):OSM \u002F CartoDB Voyager \u002F ESRI 衛星 \u002F OpenFreeMap Liberty(類 Google Maps 風格向量圖) \u002F NLSC 台灣電子地圖 \u002F GSI 日本地理院地圖\n- **當地天氣**:狀態列顯示虛擬位置的當前天氣 + 溫度(Open-Meteo,動態 SVG 圖示:太陽呼吸、雨滴下落、雪花旋轉、雷電閃爍)\n- **國旗與時區**:瞬移後自動顯示當地國旗,跨時區時 toast 提醒時差\n- **地圖釘 \u002F 使用者頭像**(狀態列):\n  - 預設「小藍人」+ 6 組內建角色 PNG(兔兔 \u002F 小狗 \u002F 小貓 \u002F 狐狸 \u002F 男孩 \u002F 女孩)+ 自訂 PNG 上傳\n  - 上傳 PNG 自動透明邊界偵測與去除,長邊縮成 88px,地圖顯示 44px,裸 PNG 透過不加底色\n  - 上傳的自訂圖與目前使用的頭像**分兩個 localStorage 格子存**,切換預設圖不會把使用者上傳的圖洗掉\n  - 點選任一張變 pending(藍框高亮),按**儲存**才套用;取消 \u002F ESC \u002F 按外面都不生效\n  - 切換後當場換地圖釘,不用瞬移才生效\n- **一鍵還原**:狀態列,清除 iPhone 虛擬定位並顯示「正在清除 \u002F 已清除請等待生效」提示\n- **停止 ≠ 還原**:停止只結束移動,虛擬定位保留;清除請按「一鍵還原」\n- **座標收藏 \u002F 分類**:\n  - 自訂座標(一格輸入 `lat, lng`)、JSON 全量匯出 \u002F 匯入(合併,不覆蓋)\n  - 新增時**自動抓取地名**(短名稱)與**國旗**(reverse geocode)\n  - **多選刪除**、**分類顏色自訂**(10 色預設 + HEX 任意色)、搜尋、排序(名稱 \u002F 日期 \u002F 最後使用)\n  - **拖曳排序**(v0.2.146+):分類與項目均可手動拖曳調整顯示順序,記在 localStorage\n  - 勾選「在地圖上顯示所有收藏」:地圖上會顯示所有收藏的精緻 pin(霓虹玻璃膠囊 + 國旗 + 聚合 Polaroid 卡片)\n  - 「點擊也要飛 GPS」勾選控制:打勾時點座標會把 iPhone 瞬移過去(預設);取消打勾則只把畫面飛過去看看,iPhone 定位不變\n  - 編輯座標時座標改變會自動刷新國旗\n- **儲存路線**:GPX 匯入 \u002F 匯出、JSON 全量匯出 \u002F 匯入\n  - **路線分類**(v0.2.133+):同名儲存可選擇覆蓋既有路線\n  - **拖曳排序**(v0.2.146+):分類與路線項目可手動排序\n  - **多點 \u002F 路線複製座標**(v0.2.151+):依目前順序輸出 `lat, lng` 一行一筆,可貼回貼上對話框或外部工具\n  - **最佳順序**(v0.2.134+):多點巡迴可一鍵跑 TSP 找最短順序,改走 BRouter 引擎避免直線估算誤差;v0.2.143+ 結果可直接帶入移動模式,toast 用使用者實際速度估時\n- **路徑點 + 路徑線**:地鐵站點風格的 S\u002F1\u002F2\u002F3 標 + 動態箭頭流動線,看得出方向感\n- **地址搜尋**:三家免費供應商任選(設定面板切換,選擇記在 localStorage)\n  - **Nominatim**(預設):OSM 官方,涵蓋全球\n  - **Photon (komoot)**(v0.2.149+):模糊搜尋 \u002F 容錯字比 Nominatim 強\n  - **Google Geocoding API**:輸入個人 API Key,完全保存在本機,中文地名與店家結果最精準\n  - 手機網頁版會跟著電腦端的選擇走(v0.2.150+),不會卡在 Nominatim 403\n- **Cooldown 防偵測**:依跳點距離動態延遲,避免異常偵測\n- **座標格式切換**:DD \u002F DMS \u002F DM\n- **右鍵選單自動防出界**:選單會用 `useLayoutEffect` 測量實際尺寸,超出視窗右 \u002F 底邊緣時自動往內推,不會被切\n\n### 使用者體驗\n\n- 啟動時 backend race condition 自動重試(最多 ~20 秒緩衝),無需手動重開\n- WebSocket 即時推播位置、進度、ETA、剩餘距離、裝置連線狀態\n- 模擬進行中切換模式 tab 不再清空地圖上的終點 \u002F 路徑 \u002F 路徑點(v0.2.90+),閒置時切換才會重置\n- 斷線自動重連 + banner 自動清除\n- **更新檢查**:啟動時從 GitHub Releases 比對版本,有新版時在底部狀態列版本號旁顯示彩色 `NEW` 膠囊提示(不再彈出對話框打斷操作),點擊版本號即跳轉到下載頁\n- **時差 chip**(狀態列,v0.2.128+):跨時區後顯示當地時間差,點開彈窗看完整時區 \u002F 城市 \u002F GMT 偏移;右下時鐘即時更新\n- **路線完成提示音**(v0.2.131+):路線跑完播一段音效,新增「設定」按鈕可關閉\n- **硬體加速 toggle**(v0.2.132+,設定面板):部分顯示卡驅動下關閉可解決畫面殘影 \u002F 黑屏 ([Issue #24](https:\u002F\u002Fgithub.com\u002Fkeezxc1223\u002Flocwarp\u002Fissues\u002F24))\n- **IP 欄位歷史**(v0.2.152+):Tunnel IP 欄位旁新增「最近」清單,可直接點選免重打\n- **Log 資料夾**按鈕(狀態列):一鍵開啟 `~\u002F.locwarp\u002Flogs\u002F` 資料夾,方便將 backend.log 附到 Issue\n- 右下角顯示**目前 App 版本**(有新版本時旁邊出現流動漸層 `NEW` 膠囊)\n- 介面語言:繁體中文 \u002F English 即時切換\n- **官方 LINE 按鈕**(側邊欄底部):有問題或建議直接聯絡作者\n- 所有狀態(座標收藏、設定、tunnel 資訊)寫在 `~\u002F.locwarp\u002F`\n\n---\n\n## 架構\n\n```\n┌─────────────────┐      IPC \u002F HTTP + WS       ┌──────────────────┐\n│ Electron + React│ ─────────────────────────► │ FastAPI backend  │\n│  (port 5173 dev)│ ◄───────────────────────── │  (port 8777)     │\n└─────────────────┘                            └────────┬─────────┘\n                                                        │ pymobiledevice3\n                                                        ▼\n                                              ┌──────────────────┐\n                                              │ iPhone (USB\u002FWiFi)│\n                                              └──────────────────┘\n```\n\n### Frontend\n\n| 技術 | 版本 | 用途 |\n| --- | --- | --- |\n| [Electron](https:\u002F\u002Fwww.electronjs.org\u002F) | 30 | Desktop shell,負責視窗管理、spawn backend、注入 tile referer |\n| [React](https:\u002F\u002Freact.dev\u002F) | 18.3 | UI framework |\n| [TypeScript](https:\u002F\u002Fwww.typescriptlang.org\u002F) | 5.5 | Type-safe JS |\n| [Vite](https:\u002F\u002Fvitejs.dev\u002F) | 5.4 | Dev server + 生產環境打包(`base: '.\u002F'` 供 `file:\u002F\u002F` 載入) |\n| [Leaflet](https:\u002F\u002Fleafletjs.com\u002F) | 1.9 | 互動地圖(底圖切換 + 自訂 divIcon 書籤\u002F路徑點標記 + 動畫 polyline) |\n| Inline SVG | n\u002Fa | 天氣圖示、書籤 pin、路徑點標、控制按鈕,完全無第三方 icon 套件 |\n| PNG 靜態資產 | n\u002Fa | 6 個地圖釘預設頭像(`src\u002Fassets\u002Favatars\u002F`),Vite 自動 hash 打包 |\n| CSS | n\u002Fa | 手寫,單一 `styles.css`,包含所有 keyframe 動畫 |\n\n### Backend\n\n| 技術 | 版本 | 用途 |\n| --- | --- | --- |\n| Python | 3.13 | 主 runtime(v0.2.4 起從 3.12 升級) |\n| [FastAPI](https:\u002F\u002Ffastapi.tiangolo.com\u002F) | 0.110+ | REST API + WebSocket |\n| [uvicorn](https:\u002F\u002Fwww.uvicorn.org\u002F) | 0.29+ | ASGI server(`:8777`) |\n| [websockets](https:\u002F\u002Fwebsockets.readthedocs.io\u002F) | 12+ | 即時位置\u002F狀態推播給前端 |\n| [pymobiledevice3](https:\u002F\u002Fgithub.com\u002Fdoronz88\u002Fpymobiledevice3) | 9.9+ | iOS 裝置協議(DVT \u002F RemoteServices \u002F lockdown \u002F LegacyLocationService) |\n| [pydantic](https:\u002F\u002Fdocs.pydantic.dev\u002F) | 2+ | 資料驗證(schemas) |\n| [httpx](https:\u002F\u002Fwww.python-httpx.org\u002F) | 0.27+ | OSRM \u002F OSRM FOSSGIS \u002F Valhalla \u002F BRouter \u002F Nominatim \u002F TimezoneDB HTTP 呼叫 |\n| [gpxpy](https:\u002F\u002Fgithub.com\u002Ftkrajina\u002Fgpxpy) | 1.6+ | GPX 路線解析 |\n\n### WiFi Tunnel(整合於 backend,v0.2.3+,iOS 17+ only)\n\n| 技術 | 用途 |\n| --- | --- |\n| pymobiledevice3 `start_tcp_tunnel()` | 建立 RSD tunnel(in-process asyncio task) |\n| pytun-pmd3 | Windows TUN 介面(wintun.dll,已捆入 backend exe) |\n\n### 外部服務(全部免費)\n\n| 服務 | 呼叫端 | 用途 | 需要 API Key |\n| --- | --- | --- | --- |\n| [OSRM 公用 demo](https:\u002F\u002Fproject-osrm.org\u002F) | backend | 路線規劃 + `\u002Ftable` 多點優化(walking \u002F driving profile),預設來源 | 否 |\n| [OSRM FOSSGIS 鏡像](https:\u002F\u002Frouting.openstreetmap.de\u002F) | backend | 同 OSRM 引擎,可在「路徑來源」切換為備援 | 否 |\n| [Valhalla(FOSSGIS)](https:\u002F\u002Fvalhalla1.openstreetmap.de\u002F) | backend | 不同的路徑引擎,「路徑來源」第三個選項,OSRM 全掛時可用 | 否 |\n| [BRouter](https:\u002F\u002Fbrouter.de\u002F) | backend | 第四個獨立引擎,OSM 資料 + 自家路徑引擎,涵蓋全球,單車 \u002F 健行 \u002F 開車 profile 齊全 | 否 |\n| [Nominatim](https:\u002F\u002Fnominatim.openstreetmap.org\u002F) | backend | 正向 \u002F 反向地理編碼、地名查詢(含 POI 智慧 short_name 選擇,預設地址搜尋來源) | 否 |\n| [Photon (komoot)](https:\u002F\u002Fphoton.komoot.io\u002F) | backend | 地址搜尋第二供應商(v0.2.149+),模糊搜尋 \u002F 容錯字比 Nominatim 強 | 否 |\n| [Google Geocoding API](https:\u002F\u002Fdevelopers.google.com\u002Fmaps\u002Fdocumentation\u002Fgeocoding) | backend | 地址搜尋備援來源(可選,免費 10K req\u002F月);使用者於設定輸入自己的 API Key | 是(使用者自備) |\n| [Open-Meteo](https:\u002F\u002Fopen-meteo.com\u002F) | **frontend(直連)** | 虛擬位置當地天氣(氣溫 + WMO weather_code);每個用戶自己 IP 各自 10000 req\u002Fday | 否 |\n| [TimezoneDB](https:\u002F\u002Ftimezonedb.com\u002F) | backend | 座標 → 時區 + GMT 偏移,跨時區 toast 提醒 | 是(內建 Key) |\n| [flagcdn.com](https:\u002F\u002Fflagcdn.com\u002F) | frontend | 國旗 PNG(`w20\u002F{cc}.png`、`w40\u002F{cc}.png`) | 否 |\n| [CartoDB Voyager](https:\u002F\u002Fcarto.com\u002F) | frontend tile | 地圖底圖(OSM 資料,免費授權) | 否 |\n| [ESRI World Imagery](https:\u002F\u002Fwww.esri.com\u002F) | frontend tile | 衛星圖層(圖層切換) | 否 |\n| [OpenFreeMap Liberty](https:\u002F\u002Fopenfreemap.org\u002F) | frontend tile | 向量圖層(類 Google Maps 風格,經 MapLibre GL 渲染) | 否 |\n| [NLSC 國土測繪中心](https:\u002F\u002Fmaps.nlsc.gov.tw\u002F) | frontend tile | 台灣電子地圖(政府公開資料) | 否 |\n| [GSI 国土地理院](https:\u002F\u002Fwww.gsi.go.jp\u002F) | frontend tile | 日本地理院地圖 | 否 |\n| OpenStreetMap raster | frontend tile | 標準 OSM 圖層(主要) | 否 |\n| [GitHub Releases](https:\u002F\u002Fgithub.com\u002Fkeezxc1223\u002Flocwarp\u002Freleases) | frontend | 啟動時檢查新版本(純 HTTP,無遙測) | 否 |\n\n### 打包工具\n\n| 工具 | 用途 |\n| --- | --- |\n| [PyInstaller](https:\u002F\u002Fpyinstaller.org\u002F) | Python → 單檔 exe(backend,含內建 tunnel) |\n| [electron-builder](https:\u002F\u002Fwww.electron.build\u002F) | Electron 打包成 NSIS 安裝檔 |\n| NSIS | Windows 安裝器 |\n\n### 核心模組(backend\u002Fcore\u002F)\n\n| 模組 | 職責 |\n| --- | --- |\n| `simulation_engine.py` | 中央控制器,管理狀態轉換、任務生命週期、`_move_along_route()` 核心移動迴圈、`EtaTracker` |\n| `device_manager.py` | 裝置探索、USB \u002F WiFi Tunnel 連線管理 |\n| `navigator.py` | 單一目的地 OSRM 導航 |\n| `route_loop.py` | 封閉路線無限循環 |\n| `multi_stop.py` | 多點依序經過,可停留 |\n| `random_walk.py` | 在半徑內隨機漫遊 |\n| `joystick.py` | 即時方向\u002F力度控制 |\n| `teleport.py` \u002F `restore.py` | 瞬移 \u002F 恢復 |\n\n### 關鍵設計\n\n- **WebSocket 位置推播**:backend 每 tick(`update_interval` 由速度 profile 決定)發 `position_update` 事件,前端即時更新地圖游標 + ETA bar\n- **速度解析**:`config.resolve_speed_profile(mode, speed_kmh, speed_min_kmh, speed_max_kmh)` 統一處理「模式預設 \u002F 固定自訂 \u002F 隨機範圍」三種輸入,優先序 `range > 固定 > 預設`\n- **In-process WiFi tunnel**:backend 自 v0.2.3 起直接在主 event loop 內執行 `start_tcp_tunnel()`,不再 spawn 獨立 helper exe\n- **Runtime 狀態目錄**:一律寫入 `~\u002F.locwarp\u002F`(bookmarks \u002F settings \u002F tunnel info),避免 PyInstaller 的 `_MEIPASS` 臨時目錄問題\n- **Tile referer \u002F OSM 替換**:OSM 的 tile 服務封鎖散佈型應用,已改用 CartoDB(OSM 資料源、CARTO 代管 CDN、免 referer)\n- **多裝置群組模式**(v0.2.0+, 三裝置上限):同步瞬移 \u002F 同步移動,primary 不被後插裝置搶走,後插的裝置自動同步到 primary 的位置並接續 primary 正在執行的任務(fanout)\n- **Idle-gated 地理查詢**:reverse geocode + timezone + 天氣僅在 idle \u002F teleport \u002F disconnect 狀態且位置變動 ≥ 100m 才觸發,避免跑動態模式時 HTTP 對 DVT 頻道產生 contention\n- **並行查詢地理資訊**(v0.2.147+):國旗 \u002F 地標 \u002F 時差 \u002F 天氣同時打,單一服務慢時其他資訊不再跟著卡住\n- **前端天氣直連**:`lookupWeather()` 直接從 renderer 打 Open-Meteo,每個用戶自己 IP 各自計算配額,不透過 backend proxy 避免全體用戶共享一個來源 IP 爆量\n- **座標國旗自動補全**:新增 \u002F 編輯座標時 reverse geocode 帶出 country_code 並渲染為國旗,座標變動時自動刷新\n\n---\n\n## 開發環境\n\n### 先決條件\n\n- Windows 10 \u002F 11\n- Python **3.13**(backend + WiFi tunnel 共用)\n- Node.js 18+\n- iPhone 已透過 iTunes \u002F Apple Devices 配對過這台電腦\n- iOS 16+ 需開啟「開發人員模式」\n\n### 首次設置\n\n```bash\n# 1. 後端依賴(含 WiFi tunnel)\npy -3.13 -m pip install -r backend\u002Frequirements.txt\n\n# 2. 前端依賴\ncd frontend\nnpm install\n```\n\n### 啟動(開發模式)\n\n雙擊 `LocWarp.bat`, 會自動提權並呼叫 `start.py`,同時啟動:\n- backend(`:8777`)\n- Vite dev server(`:5173`)\n- 預設瀏覽器自動開啟 `http:\u002F\u002Flocalhost:5173`(走瀏覽器,不啟 Electron)\n\n或手動:\n\n```bash\n# 終端 1, backend\ncd backend && py -3.13 main.py\n\n# 終端 2a, 前端走瀏覽器(等同 LocWarp.bat 的行為)\ncd frontend && npx vite --host --port 5173\n\n# 終端 2b, 前端走 Electron 視窗(同安裝檔執行體驗)\ncd frontend && npm run start\n```\n\n> 安裝檔(`LocWarp.Setup.x.x.x.exe`)跑的是 Electron 包;`LocWarp.bat` \u002F `start.py` 是開發用,故走瀏覽器。要在開發環境裡測 Electron 視窗的行為(例如 IPC、分頁邏輯),用上面的 2b。\n\n---\n\n## 打包(產出安裝檔)\n\n### 一次性安裝打包工具\n\n```bash\npy -3.13 -m pip install pyinstaller\ncd frontend && npm install -D electron-builder\n```\n\n### 一鍵建置\n\n```bash\nbuild-installer.bat\n```\n\n依序執行:\n1. **PyInstaller(3.13)** 編譯 backend(含 WiFi tunnel)→ `dist-py\u002Flocwarp-backend\u002F`\n2. **Vite** 建置前端 → `frontend\u002Fdist\u002F`\n3. **electron-builder** 產出 NSIS 安裝檔 → `frontend\u002Frelease\u002FLocWarp Setup X.Y.Z.exe`(~110 MB)\n\n產物為單一 exe,使用者無需安裝 Python \u002F Node \u002F 任何套件。\n\n---\n\n## 使用者端需求\n\n**[下載安裝檔](https:\u002F\u002Fgithub.com\u002Fkeezxc1223\u002Flocwarp\u002Freleases)**\n\n使用安裝檔的使用者需要以下四項前置:\n\n### 1. 安裝 Apple USB driver\n\nWindows 需要 Apple 的 USB driver 才能與 iPhone 溝通。下列兩種方式**擇一**即可:\n\n- **傳統桌面版 iTunes**: [iTunes for Windows (64-bit)](https:\u002F\u002Fsecure-appldnld.apple.com\u002Fitunes12\u002F047-76416-20260302-fefe4356-211d-4da1-8bc4-058eb36ea803\u002FiTunes64Setup.exe)\n- **Microsoft Store 的 iTunes**: [商店頁面](https:\u002F\u002Fapps.microsoft.com\u002Fdetail\u002F9pb2mz1zmb1s)\n- **Microsoft Store 的「Apple Devices」**(iTunes 兩個版本都不行時的備案): [商店頁面](https:\u002F\u002Fapps.microsoft.com\u002Fdetail\u002F9np83lwlpz9k?hl=zh-TW&gl=TW)\n\n> **補充:** 三種擇一即可,裝一個就好。多數用戶裝桌面版 iTunes 就能用;若 iTunes(桌面版或 Microsoft Store 版)都抓不到 iPhone,社群回報改裝 **Apple Devices** 可以成功。\n\n### 2. USB 連接並信任此電腦\n\n首次使用前,用 USB 線接上 iPhone,iPhone 會跳「要信任這部電腦嗎?」,點 **信任** 並輸入密碼。這會產生 pair record,後續 LocWarp 才能與裝置通訊。\n\n### 3. 開啟開發人員模式(iOS 16+)\n\niPhone 上:**設定 → 隱私權與安全性 → 開發者模式 → 開啟**\n\n開啟後裝置會要求重啟。重啟後會再次確認「啟用開發者模式?」,點啟用。\n\n### 4. WiFi Tunnel(選用)\n\n若要拔掉 USB 改走無線連線:\n- iPhone 與電腦必須在**同一個 WiFi 網段**\n- 第一次仍需要先用 USB 配對過(步驟 2)\n- LocWarp 內按 **Start WiFi Tunnel** 會建立 RSD tunnel,之後 USB 可拔除\n\n#### 連線模式差異\n\n| 連線方式 | 鎖屏影響 | 建議設定 |\n| --- | --- | --- |\n| **USB 有線** | ![Yes](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002F可鎖屏-4caf50?style=flat-square) 可自由鎖定螢幕 | n\u002Fa |\n| **WiFi Tunnel** | ![No](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002F不可鎖屏-f44336?style=flat-square) 鎖屏會導致網路介面休眠,Tunnel 中斷 | 建議關閉自動鎖定以維持連線 |\n\n> **注意:** **WiFi Tunnel 模式下 iPhone 螢幕熄滅會造成網路介面進入休眠狀態,導致 RSD Tunnel 中斷連線。**\n>\n> 建議執行以下任一設定以避免連線中斷:\n> - **關閉自動鎖定**:設定 → 顯示與亮度 → 自動鎖定 → **永不**\n> - **保持 LocWarp 相關畫面於前景執行**(避免系統進入低功耗模式)\n> - **連接充電線並維持螢幕常亮**\n>\n> 若僅透過 USB 連線使用,則無此限制,iPhone 可正常鎖屏不影響定位模擬。\n\n---\n\n安裝後桌面\u002F開始選單出現 **LocWarp** 捷徑。開啟時會要求管理員權限(WiFi tunnel 建 TUN 介面必需)。\n\n---\n\n## 專案結構\n\n```\nlocwarp\u002F\n├── backend\u002F                 # FastAPI + pymobiledevice3\n│   ├── api\u002F                 # HTTP endpoints\n│   ├── core\u002F                # Simulation engine + handlers\n│   │   ├── simulation_engine.py\n│   │   ├── navigator.py\n│   │   ├── route_loop.py\n│   │   ├── multi_stop.py\n│   │   ├── random_walk.py\n│   │   ├── joystick.py\n│   │   └── device_manager.py\n│   ├── services\u002F            # Location service, interpolator, bookmarks\n│   ├── models\u002Fschemas.py    # Pydantic models\n│   ├── config.py            # Speed profiles, cooldown table\n│   ├── main.py              # Entrypoint\n│   └── locwarp-backend.spec # PyInstaller spec\n│\n├── frontend\u002F                # Electron + React\n│   ├── electron\u002Fmain.js     # Electron entry, spawns backend in packaged mode\n│   ├── src\u002F\n│   │   ├── App.tsx\n│   │   ├── components\u002F      # MapView, ControlPanel, EtaBar, etc.\n│   │   ├── hooks\u002F           # useSimulation, useDevice, useBookmarks\n│   │   └── services\u002Fapi.ts\n│   ├── build\u002Ficon.ico       # App icon\n│   └── package.json         # electron-builder config\n│\n├── start.py                 # Dev launcher (used by LocWarp.bat)\n├── stop.py\n├── LocWarp.bat              # Dev entry (auto-elevates)\n└── build-installer.bat      # Build installer (one-shot)\n```\n\n---\n\n## 疑難排解\n\n| 症狀 | 可能原因 \u002F 解法 |\n| --- | --- |\n| Tunnel 啟動後 backend 連不上 | 確認以系統管理員身份啟動 |\n| `No such service: com.apple.instruments.dtservicehub` (iOS 17+\u002F26) \u002F LocWarp 跳「iPhone 上未偵測到 DDI」 | v0.2.58 起 LocWarp 不再自動掛 DDI,請用下列任一工具幫 iPhone 掛一次 DDI 後再回來使用:Xcode、愛思助手、3uTools、pymobiledevice3 CLI。也可先「設定 → 隱私權與安全性 → **開發者模式** 關閉,重開機,再次開啟」,然後用上述工具重新掛一次。 |\n| **開發者模式未顯示**(iOS 16+) | v0.2.61 起,LocWarp 連線後在狀態列會出現「**顯示開發者模式選項**」按鈕,點下去 iPhone 設定裡就會出現開發者模式(不用側載 IPA)。若按鈕失敗或想手動處理,可參考下方 [附錄:iPhone 開啟開發者模式(Windows 流程)](#附錄iphone-開啟開發者模式windows-流程) 的側載方式作為備援。 |\n\n---\n\n### 附錄:iPhone 開啟開發者模式(Windows 流程)\n\niOS 16+ 的「設定 → 隱私權與安全性 → 開發者模式」預設**不顯示**。Apple 要求裝置必須被開發者簽署之 App 部署過(或直接對 AMFI 服務下 reveal 指令),該選項才會出現。\n\n#### 主要流程(推薦,v0.2.61 起)\n\nLocWarp 連上裝置後,狀態列會出現「**顯示開發者模式選項**」按鈕(僅在偵測到 iPhone 的 Developer Mode 未啟用時顯示)。點一下,後端呼叫 AMFI 服務幫 iPhone 寫下顯示 marker,然後:\n\n1. iPhone 上完全關掉「設定」App(從底部往上滑移除)\n2. 重新打開「設定」\n3. 「隱私權與安全性」往下拉,應該會看到「**開發者模式**」\n4. 點進去自行開啟(iPhone 會要求先關閉螢幕密碼 + 重啟一次)\n\n完成後 LocWarp 狀態列的按鈕會自動消失。\n\n#### 備援流程(側載 IPA)\n\n如果 LocWarp 的按鈕不能用(例如裝置沒透過 USB 連線,純 WiFi 模式下 AMFI 服務 advertising 不到),可改用傳統側載 IPA 方式:\n\n1. 安裝 [**Sideloadly**](https:\u002F\u002Fsideloadly.io\u002F)\n2. 於 [**Decrypt IPA Store**](https:\u002F\u002Fdecrypt.day\u002F) 或 [**ARM Converter Decrypted App Store**](https:\u002F\u002Farmconverter.com\u002Fdecryptedappstore\u002Fus) 等解密 IPA 網站取得任意 IPA 檔案。建議挑選體積較小的檔案管理類 App 以縮短側載時間\n3. 將 IPA 拖入 Sideloadly 視窗\n4. USB 連接 iPhone,於 Sideloadly 輸入個人 Apple ID\n5. 按下 **Start** 執行側載,等待完成\n6. iPhone 上 設定 → 隱私權與安全性 → 滑至底部 → 會出現「**開發者模式**」,開啟該開關\n7. 系統提示重新啟動,重啟後再次確認開發者模式為開啟狀態\n\n完成後即可回到 LocWarp 建立連線。iOS 17+ 還需額外用 Xcode \u002F 愛思助手 \u002F 3uTools \u002F pymobiledevice3 CLI 幫 iPhone 掛過一次 Developer Disk Image,LocWarp 本身不會自動掛(v0.2.58 起)。\n\n---\n\n## License\n\n本專案採用 **MIT License** 授權釋出, 詳見 [LICENSE](LICENSE)。\n\n允許自由使用、修改、再散佈與商業利用,惟須保留原始著作權與授權聲明。\n\n---\n\n## Disclaimer(免責聲明)\n\n### 1. 僅限學術與研究用途\n\n本專案開發初衷僅供地理資訊系統(GIS)研究、行動應用程式開發測試、位置服務原型驗證及相關技術探討使用。請勿將本工具用於任何非法用途,或違反第三方服務條款、平台政策之行為。\n\n### 2. 帳號封禁風險\n\n本專案透過 pymobiledevice3 介接 Apple DVT \u002F RemoteServices 協議,以模擬 GPS 訊號達成虛擬定位。若將本工具用於基於地理位置的遊戲(例如 Pokémon GO、Ingress、Monster Hunter Now 等)或社交、打卡、物流類應用,可能違反該平台的服務條款,進而導致帳號遭警告、限制、封鎖或永久停權。**開發者對因使用本工具所造成之任何帳號損失、虛擬財產損害或衍生糾紛,概不負責。**\n\n### 3. 系統與硬體風險\n\n本專案於 WiFi Tunnel 模式下需以**系統管理員權限**執行,以建立 TUN 虛擬網路介面並與 iOS 裝置協商 RSD(Remote Service Discovery)通道。雖然程式碼已經內部測試,但開發者不保證於所有 Windows 版本、硬體組合、網路環境下皆能穩定運行。常見的潛在狀況包括:\n\n- 與 VPN 軟體、第三方防火牆或網路虛擬化工具發生衝突,導致 Tunnel 建立失敗或系統網路暫時異常\n- 程式非正常結束時殘留的 TUN 介面需重新啟動系統始能清除\n- 連線中斷時需手動重試或重啟應用程式\n\n使用者應自行評估上述風險並承擔因此所產生之任何後果。本專案僅操作本身所建立之臨時網路介面與自身設定檔(位於 `~\u002F.locwarp\u002F`),**不會修改 iOS 裝置內任何使用者資料,亦不會變更作業系統核心檔案或既有裝置配對記錄**。\n\n### 4. 地圖資料準確性\n\n本專案前端採用 Leaflet,底圖由 OpenStreetMap 之衍生供應商(CartoDB)提供,路線規劃與地理編碼則使用 OSRM 與 Nominatim 公共 API。地圖顯示之座標、路徑、地址資訊**僅供參考**,開發者不保證其完整性、即時性、正確性或與實際地理位置完全一致。使用者在依照地址搜尋、路線導航、隨機漫步等結果進行定位模擬前,應自行比對地圖顯示是否符合預期。\n\n### 5. 使用者責任\n\n使用者應自行遵守所在地之法律法規,包括但不限於《個人資料保護法》《電腦處理個人資料保護法》《著作權法》及相關國際條約。任何因濫用、誤用或違法使用本工具所引發之法律糾紛、民事賠償或刑事責任,均由使用者個人獨自承擔,與本專案之開發者及貢獻者無涉。\n\n---\n\n**下載、安裝或執行本軟體,即視為您已完整閱讀並同意上述全部免責條款。**\n\n**若不同意,請立即停止使用並移除本軟體。**\n","LocWarp 是一个在 Windows 上模拟 iPhone GPS 定位的工具，支持 USB 或 WiFi 连接。它提供了多种模拟模式，包括直接跳点、导航、路线循环、多点停留、随机漫步和摇杆操作等。该项目使用 TypeScript 编写，具备良好的跨平台兼容性和丰富的定位控制功能。适用于需要测试基于地理位置的应用程序或服务的开发者，以及那些希望在不实际移动设备的情况下更改其位置信息的用户。",2,"2026-06-11 02:46:28","CREATED_QUERY"]