鴻蒙開發工具 SandboxFinder，用瀏覽器直接翻 App 沙箱檔案

用 AI 摘要這篇文章：

ChatGPT Claude Perplexity Google Grok

鴻蒙 App 跑起來之後，開發者最常做的一件事是翻沙箱：看日誌有沒有照預期寫進 filesDir、cache 堆了多少暫存、資料庫的表長成什麼樣。沙箱是 HarmonyOS 把每個應用程式的資料關在各自目錄裡的隔離設計，App 只看得到自己那份，這對使用者是安全保障，對開發者卻代表每次想看一眼內部檔案，都得把裝置接上電腦，用 hdc 指令把檔案一個個拉下來，改完再推回去，一輪除錯就磨在這種來回裡。開源專案 SandboxFinder 給了另一種答案：在 App 裡啟動一個小型 HTTP 服務，然後在任何電腦的瀏覽器輸入裝置 IP 加上 7777，整個應用沙箱就變成一個網頁版的檔案總管，點一下就能預覽，拖曳就能上傳。

先把它的身分講清楚，免得期待錯方向。SandboxFinder 不是一支安裝在手機上的 App，而是要裝進你自己專案裡的開發函式庫，授權 Apache-2.0，透過鴻蒙官方的套件管理器 ohpm 安裝，也上架在 ohpm 三方庫中心倉。它由成都開發者仙銀（GitHub 帳號 iHongRen）維護，2025 年 7 月第一次發布，2026 年 5 月推出大改版的 2.0。這篇我把它整個專案抓下來逐檔讀過，能做的事、該守的邊界、以及版本演進，都從原始碼核對過一遍。

接入只要三步：裝套件、一行程式碼、打開瀏覽器

第一步在專案根目錄執行 ohpm install @cxy/sandboxfinder。第二步在 EntryAbility 的 onWindowStageCreate 裡加幾行：官方範例把載入包在 BuildProfile.DEBUG 的判斷裡，用動態 import 呼叫 SandboxFinder.run()，順手再加一句 setWindowKeepScreenOn(true)，避免螢幕熄掉把服務掛起。第三步看控制台輸出，服務起來後會印一段分隔線，告訴你瀏覽器該開哪個網址，實機的話長得像 http://192.168.2.38:7777，前提是手機和電腦在同一個 Wi-Fi。

用模擬器的話多一道手續：模擬器的網路對外需要轉埠，執行 hdc -t 127.0.0.1:5555 fport tcp:7777 tcp:7777 之後，改開 http://127.0.0.1:7777 就行。這一步官方文件寫得很明白，卻是最容易讓人以為工具壞掉的地方；如果轉了埠還是連不上，文件提醒先關掉電腦上的代理軟體再試。預設監聽 7777 埠，要改就呼叫 run({ port: 8080 }) 傳進去。

瀏覽器裡能做什麼：從看日誌到開資料庫表

網頁打開後，左側欄是沙箱目錄的快速入口，filesDir、cacheDir、tempDir、databaseDir 等沙箱目錄一鍵直達，下面還有一個應用資訊區塊，顯示 App 名稱、bundle 名稱與版本號，這些是它呼叫系統的 bundleManager 現查出來的，不是寫死的裝飾。主畫面是檔案清單，可以按名稱、大小、時間排序，搜尋框是即時過濾。點開檔案，文字、圖片、影片、音訊都直接內嵌預覽；SQLite 資料庫檔也點得開，表與內容攤在網頁裡，這對驗證資料寫入是否正確特別省事，不必再拉檔回電腦用其他工具開。

Pin

預覽背後的機制值得看一眼，它決定了你看影片時發生什麼事。文字檔走 API 直接回內容；媒體類則不然，伺服器會把檔案複製一份到網頁伺服器的靜態目錄、給你一條直鏈讓瀏覽器自己串流，這個副本帶快取，上限十個檔案、超出就淘汰最久沒看的。前端整包是單一個約 83KB 的 index.html，藏在套件的資源檔裡，我讀它的原始結構：介面用 Vue 3，SQLite 預覽靠 sql.js 在瀏覽器端解析，資料庫內容不會被送到別的地方；不過這些函式庫本體是開頁時從公共 CDN 載入的，裝置只供出 HTML 骨架，在完全沒有對外網路的環境，頁面與 SQLite 預覽會受影響。

順手補一份目錄語意的速查，因為知道該進哪扇門，等於知道問題該往哪裡找。filesDir 放的是 App 自己的永久檔案，日誌與下載內容通常在這；cacheDir 是快取，系統空間吃緊時可以被清走；tempDir 放用完即丟的暫存；databaseDir 收 SQLite 這類資料庫檔。日誌沒出現在 filesDir，先懷疑寫入邏輯；cacheDir 無限長大，檢查的是快取策略。這份地圖對剛接觸鴻蒙開發的人比任何功能清單都實用。

操作面也不只是看。從原始碼裡註冊的路由可以對出完整能力表：新增檔案、刪除、重新命名、複製、建資料夾，上傳則走分塊傳輸，前端用 File.slice 切塊、以 isFirst 旗標標記續接，支援拖放與多選，官方文件承諾的是大檔案分塊上傳，沒有給出體積上限；下載端提供直鏈，這讓它有自動化的空間，例如用腳本定時抓走 App 產生的日誌。這些是文件宣稱加上程式碼可核對的能力，實際在裝置上的速度與穩定度，要留給你自己的第一台裝置回答。

安全設計要自己看：它是一支沒上鎖的區網服務

效率的來源同時是風險的來源。把這個專案的伺服器端程式碼讀完，會看到 10 條 POST API：查伺服器資訊、查 App 資訊、讀檔、列目錄、建檔、刪檔、搬移、複製、建資料夾、上傳。每一條都沒有認證，沒有 token，沒有金鑰；服務啟動時還以無參數方式啟用了跨來源資源共享（CORS），對照它底層依賴的 @cxy/webserver 原始碼，無參數時回應標頭的允許來源是星號，任何網頁來源都放行。換句話說，誰能連到你的手機，誰就能動你的沙箱。

開發者最可能問的三個問題，邊界在這裡講清楚。外面網際網路上的陌生人連得到嗎？服務聽在手機的區網位址上，你家 Wi-Fi 裡的任何裝置都在界內，界外要碰到手機得先過你的路由器，所以暴露範圍基本上就是你所處的區域網路。正式上架的版本會帶著這個服務嗎？照官方範例把載入包在 DEBUG 判斷裡，release 建置根本不會載入這段程式碼，這是作者明寫的建議接法，也是使用它最起碼的紀律。檔案會被送到雲端嗎？不會，服務跑在裝置上，頁面本體也從裝置內部提供，你的檔案在瀏覽器和手機之間點對點移動；它的權限清單只有上網與取得網路資訊兩項，連讀寫儲存的權限都沒有申請，因為沙箱本來就是 App 自己的地盤。

沒有認證這件事，讀起來像缺陷，放在開發工具的脈絡裡更像一個取捨。除錯是高頻操作，如果每次打開瀏覽器都要先去控制台抄一組 token 貼進網址，這個工具省下的時間會在輸入框裡還回去；於是它把安全邊界整個畫在網路層，你所在 Wi-Fi 的範圍就是它的門禁。這個選擇能不能接受，取決於你連的網路可不可信，而這個判斷沒有人能替你做。

所以它危險嗎？把 debug 版 App 長時間掛在不可信的 Wi-Fi 上跑，任何同網段的人都能翻你的沙箱，這是真實的攻擊面；把它當成開發機上的除錯工具、連自家網路、用完即關，它就是原地解決 hdc 來回摩擦的乾淨做法。同樣把邊界畫在區網內、不經雲端帳號的設計，之前介紹過的PlayBridge 投屏工具是同一個思路，只是這次開的門直通你的應用資料。工程上「沙箱」這個詞還有另一個常見場景是拿來隔離部署 AI Agent，想了解那條線可以看OpenSandbox 的部署與安全設定。

2.0 版把那扇門縮小成你可以指定的樣子

這個專案 2025 年 7 月的 1.0，底層是作者自己手寫的 TCP Socket HTTP 伺服器；2026 年 5 月 9 日的 2.0 把整個底層換成他自己的另一個開源專案 @cxy/webserver，一套 Express 風格的鴻蒙端網頁伺服器函式庫，同樣走 Apache-2.0，到 2026 年 8 月都還有提交在推進。對使用者來說，換底層最有感的部分是暴露範圍變成可配置：run() 的參數從 1.0 的兩個位置參數（port、context）整併成一個設定物件，port、address、rootDir、context 全部可選，就連網頁介面的側欄、應用資訊區塊、關於區塊也各有一個開關可以關掉。

其中最值得用的是 rootDir。預設值是一條斜線，代表整個沙箱攤開；改成 run({ rootDir: context.filesDir }) 就只開 filesDir 這一格抽屜，網頁裡的路徑也會以相對路徑顯示，看不出沙箱的完整結構。防護上，指定 rootDir 之後，路徑裡的「..」會被剝除，防止穿越到根目錄之外，這層檢查在原始碼裡白紙黑字；不過要理解它的前提，預設全開模式本來就允許絕對路徑，這層保護是在你主動限縮範圍之後才生效的。

2.0 也把「用完即關」從口號變成 API。服務啟動後 run() 回傳一個帶 address 與 port 的物件，官方範例把它存進 AppStorage，讓你把網址顯示在自己的介面上，不必每次翻控制台；要收攤就呼叫 SandboxFinder.stop()，服務停下來、App 照常運作。對前面講的使用紀律來說，這是實際的支撐：把開門與關門都做成一行程式碼，養成習慣的成本就低了。

有個細節值得記下來：指定瀏覽路徑這個 2.0 的招牌功能，出處是一位使用者在 2025 年 12 月提的 issue，問能不能限定要看的目錄，五個月後的 2.0 用 rootDir 回答了它。這個 repo 到目前為止只有兩則 issue 與 PR，全部關閉，樣本很小，但至少看得到有問有回應。也順帶提醒一件讀原始碼時發現的事：網路上流傳的介紹文多半寫它「基於 TCP Socket」，那是 1.0 時代的描述，2.0 之後已經換了底層，看舊文判斷現況要留意時間點。

Pin

限制與專案狀態：單人維護，鴻蒙限定

使用上的硬邊界先列清楚。它只服務鴻蒙應用開發這個場景，不寫 HarmonyOS App 的人用不到；上傳、預覽的速度與穩定度屬於裝置端行為，官方文件與原始碼回答不了，接進去之後先拿自己的 App 試一輪再說。專案本身是單人維護，目前 47 顆星、9 個 fork，最後一次提交停在 2026 年 5 月的 2.0.0；不過作者不是路過型選手，他同時維護著鴻蒙一鍵打包分發工具 hpack、讓 macOS Finder 直接用 DevEco Studio 開工程的整合工具，以及 2.0 起在底下撐著 SandboxFinder 的 webserver 函式庫，是一個持續在鴻蒙開發工具鏈上產出的開發者。對華為裝置生態有興趣的讀者，先前也寫過側載 Google 服務的風險提醒，可以對照著看這個生態的另一面。

授權是 Apache-2.0，倉庫附了條款全文，商用與修改都沒有障礙；沒有付費牆，沒有帳號系統，裝置端程式碼裡也找不到遙測；你的檔案全程不經過它的任何雲端。這些對開發者都是加分項，前提永遠是那一句：除錯期間才載入，用完就關。

適合誰，以及跨出第一步的方式

適合的輪廓很明確：你正在寫鴻蒙 App，且經常需要翻沙箱裡的日誌、暫存或資料庫；或者你要向團隊、課堂展示一個 App 的內部檔案結構，一個網址比投影 hdc 視窗體面得多；再或者你需要腳本化地定期收取 App 日誌，直鏈下載就是為這種情境留的口。不適合的也一樣明確：不碰鴻蒙開發的人，以及必須長時間在不可信網路上跑 debug build 的場景。

如果要試，建議的第一步把保守值設好：rootDir 先限定在 filesDir，連接埠照預設 7777 就好，載入嚴格放在 DEBUG 判斷內，連的網路是自己家的。這一套設定下，你拿到的是一個只開一格抽屜的瀏覽器檔案總管，而不是整個沙箱的大門。SandboxFinder 的價值與它的風險出自同一個設計，門要開多大，2.0 之後終於是你自己可以參數化的決定。