🚀 世界首個在手機上完整運行 Flutter 開發環境的解決方案

flutter build apk ✅ | flutter run + Hot Reload ✅ | 原生速度 ✅ | 一鍵安裝 ✅

中文 | English

🍴 Forked from mumumusuc/termux-flutter

📱 在 Termux 中運行 Flutter App，支援 Hot Reload！

Flutter「支援 arm64」≠「能在任何 arm64 上開發」

Flutter 假設的 Linux host 環境：

• glibc（標準 C 庫）
• 完整 POSIX
• 標準 toolchain

但 Termux 是：

• bionic libc（Android 的 C 庫，不是 glibc）
• Android sandbox + SELinux 限制
• 不同的動態連結器 (/system/bin/linker64)

對 Flutter 官方來說：這不是他們支援的 OS。

Flutter SDK 裡的 engine binaries：
bin/cache/artifacts/engine/
    ├── darwin-arm64/     ← macOS 用
    ├── linux-arm64/      ← Linux (glibc) 用
    └── android-arm64/    ← 這是 TARGET，不是 HOST！

❌ 沒有 Termux/bionic host 版本

我們從源碼交叉編譯了整個 Flutter Engine，專門為 Termux (Android/bionic) 環境打造：

• 修復 TLS 對齊問題（bionic linker 要求）
• 修復動態連結器路徑
• 編譯 host-side 工具（dart, gen_snapshot, impellerc）
• 讓 Hot Reload、APK 構建在 Termux 上原生運行

一句話：Flutter 官方支援 arm64 目標平台，但從不支援 Android 作為開發主機。我們補上了這個缺失。

本專案基於 mumumusuc/termux-flutter，實現了在 WSL (Windows Subsystem for Linux) 環境下為 Termux 交叉編譯 Flutter Engine 的完整解決方案。

✅ 已驗證：本專案已在 Android 16 設備上成功運行 Flutter 應用！

本專案是世界首個在 ARM64 Termux 上實現完整 Flutter 開發流程的解決方案！

💡 如果你發現其他能原生支援的專案，歡迎開 Issue 告訴我們！

你可以在手機/平板上完成完整的 Flutter 開發：

📱 你的 Android 設備
    ↓
🖥️ Termux 終端
    ↓
✍️ 編寫程式碼 (vim/nano/code-server)
    ↓
🔥 flutter run → 即時看到變更 (Hot Reload!)
    ↓
📦 flutter build apk → 產出可安裝的 APK
    ↓
📲 直接安裝到設備上測試

不需要電腦、不需要模擬器、不需要雲端服務！

✅ v3.41.5 正式版：所有功能已驗證可用！包含 hot reload 支援！

• 🪟 在 Windows WSL 環境下完成交叉編譯
• 🔧 修復了 Android 日誌符號缺失問題
• 📦 成功產出 flutter_3.41.5_aarch64.deb (662MB)
• 🤖 完整的自動化構建流程

⚠️ 重要：Android SDK 中的 adb 需要 Android 11+ 的系統函數 (pthread_cond_clockwait)。在 Android 10 或更舊的設備上，需要額外步驟（見下方）。

CANNOT LINK EXECUTABLE "adb": cannot locate symbol "pthread_cond_clockwait"

# 1. 安裝舊版相容的 adb
wget https://github.com/MasterDevX/Termux-ADB/raw/master/InstallTools.sh -q && bash InstallTools.sh

# 2. 用相容版本替換 Android SDK 的 adb
cp $PREFIX/bin/adb.bin $PREFIX/opt/android-sdk/platform-tools/adb

# 3. 驗證
flutter doctor

一個命令安裝 Flutter + Android SDK + NDK，完成後直接可以 flutter build apk：

curl -sL https://raw.githubusercontent.com/ImL1s/termux-flutter-wsl/master/install_flutter_complete.sh -o ~/install.sh && bash ~/install.sh

此腳本會自動安裝 Flutter、Android SDK、ARM64 NDK，並測試 APK 構建。 總大小約 1.8GB，需要 10-30 分鐘。

如果只需要 flutter run -d linux，不需要構建 APK：

curl -sL https://raw.githubusercontent.com/ImL1s/termux-flutter-wsl/master/install_termux_flutter.sh -o ~/install.sh && bash ~/install.sh

安裝完成後，重啟 Termux 或執行：

flutter doctor

此腳本只安裝 Flutter SDK (~550MB)，不含 Android SDK。

# 1. 安裝基礎依賴
pkg update && pkg install x11-repo wget openjdk-21

# 2. 下載安裝包
wget https://github.com/ImL1s/termux-flutter-wsl/releases/download/3.41.5/flutter_3.41.5_aarch64.deb

# 3. 安裝
dpkg -i flutter_3.41.5_aarch64.deb
apt --fix-broken install -y

# 4. 執行 post-install 腳本（配置 APK 構建和 hot reload）
bash $PREFIX/share/flutter/post_install.sh

# 5. 載入環境並驗證
source $PREFIX/etc/profile.d/flutter.sh
flutter doctor

⚠️ 重要：post_install.sh 會下載並配置必要的環境，包括：

• Android API 34 平台
• 官方 Dart SDK snapshots（hot reload 必需）
• Android cmdline-tools
• ELF 二進制清理（修復 linker warning）

最新版安裝腳本修復了多個關鍵問題，確保在乾淨 Termux 環境下所有功能正常：

INPUT(-lc++_shared)

# 正確的符號連結
libc++_shared.so -> ../libc++_shared.so  # 指向真實的 ELF 庫

# 一鍵構建
./build_termux_flutter.sh

# 或分步驟執行
python3 build.py sysroot --arch=arm64    # 組裝 Termux 運行時依賴
python3 build.py configure --arch=arm64 --mode=debug
python3 build.py build --arch=arm64 --mode=debug
python3 build.py debuild --arch=arm64    # 打包 .deb

安裝完成後，你需要 Termux:X11 來顯示 GUI 應用。

安裝 Termux:X11：從 GitHub Releases 或 F-Droid 下載 APK 安裝。

# 1. 在 Termux 中啟動 X11 服務
export DISPLAY=:0
termux-x11 :0 >/dev/null 2>&1 &

# 2. 打開 Termux:X11 App (會顯示黑色畫面，這是正常的)

# 3. 創建並運行 Flutter 專案
flutter create hello_termux
cd hello_termux
flutter run -d linux

💡 備選方案：如果 X11 設置困難，也可以用 Web 模式預覽：

flutter run -d web-server --web-port=8080

然後在瀏覽器打開 http://localhost:8080

✅ 已驗證可用：APK 構建功能已在 ARM64 設備上驗證成功！（2026-03-25）

如果你使用 install_flutter_complete.sh 一鍵安裝，所有環境已配置完成，可直接構建 APK。 手動安裝 deb 的用戶需要額外配置 Android SDK。

如果你使用了上方的 install_flutter_complete.sh 一鍵安裝，APK 構建環境已經完全配置好：

# 直接創建專案並構建
flutter create myapp
cd myapp
flutter build apk --release

首次構建約需 3-5 分鐘（下載 Gradle 依賴）

# 更新套件並安裝 JDK
pkg update
pkg install openjdk-21 git wget

wget https://github.com/mumumusuc/termux-android-sdk/releases/download/35.0.0/android-sdk_35.0.0_aarch64.deb
dpkg -i --force-architecture android-sdk_35.0.0_aarch64.deb

# 加入 ~/.bashrc 或 ~/.zshrc
export ANDROID_HOME=$PREFIX/opt/android-sdk
export PATH=$PATH:$ANDROID_HOME/platform-tools:$ANDROID_HOME/cmdline-tools/latest/bin

# 重要：不要設置 JAVA_HOME，讓 Gradle 自動從 PATH 找到 Java
# 如果已設置，請取消：
unset JAVA_HOME

source ~/.bashrc

# 設定 Android SDK 路徑
flutter config --android-sdk $ANDROID_HOME

# 接受 Android 授權
flutter doctor --android-licenses

# 檢查環境
flutter doctor

# 下載 ARM64 NDK（約 538MB）
cd ~
wget https://github.com/lzhiyong/termux-ndk/releases/download/android-ndk/android-ndk-r27b-aarch64.zip

# 解壓到 Android SDK 的 NDK 目錄
mkdir -p $ANDROID_HOME/ndk
unzip android-ndk-r27b-aarch64.zip -d $ANDROID_HOME/ndk/

# 重命名為標準版本號（Flutter 需要）
mv $ANDROID_HOME/ndk/android-ndk-r27b $ANDROID_HOME/ndk/27.1.12297006

# 驗證安裝
ls $ANDROID_HOME/ndk/27.1.12297006/toolchains/llvm/prebuilt/linux-aarch64/bin/clang

# 安裝 Termux 的 cmake 和 ninja
pkg install cmake ninja

# 修復 CMake（Android SDK 的 CMake 是 x86_64）
# 首次構建時會下載 CMake，之後執行以下命令：
rm -rf $ANDROID_HOME/cmake/*/bin
mkdir -p $ANDROID_HOME/cmake/3.22.1/bin
ln -s $PREFIX/bin/cmake $ANDROID_HOME/cmake/3.22.1/bin/cmake
ln -s $PREFIX/bin/ninja $ANDROID_HOME/cmake/3.22.1/bin/ninja

# 首次構建後，找到 Gradle 緩存的 aapt2 位置並替換
# 路徑格式：~/.gradle/caches/*/transforms/*/transformed/aapt2-*-linux/aapt2
find ~/.gradle/caches -name "aapt2" -path "*/aapt2-*-linux/*" 2>/dev/null | while read f; do
    rm -f "$f"
    ln -s $ANDROID_HOME/build-tools/35.0.0/aapt2 "$f"
    echo "Fixed: $f"
done

FLUTTER_ROOT=$PREFIX/opt/flutter
mkdir -p $FLUTTER_ROOT/bin/cache/artifacts/engine/common/flutter_patched_sdk_product
cp -r $FLUTTER_ROOT/bin/cache/artifacts/engine/common/flutter_patched_sdk/* \
      $FLUTTER_ROOT/bin/cache/artifacts/engine/common/flutter_patched_sdk_product/

cd your_flutter_project
echo "ndk.dir=$ANDROID_HOME/ndk/27.1.12297006" >> android/local.properties

android {
    ndkVersion = "27.1.12297006"  // 替換原來的 flutter.ndkVersion
    // ... 其他設定
}

# 創建專案
flutter create myapp
cd myapp

# 構建 Release APK（無需額外參數！）
flutter build apk --release

# 1. 創建專案
flutter create myapp
cd myapp

# 2. 配置 NDK 版本
echo "ndk.dir=$ANDROID_HOME/ndk/27.1.12297006" >> android/local.properties
sed -i 's/ndkVersion = flutter.ndkVersion/ndkVersion = "27.1.12297006"/g' android/app/build.gradle.kts

# 3. 首次構建（會失敗，但會下載必要工具）
flutter build apk --release 2>&1 || true

# 4. 修復 CMake
rm -rf $ANDROID_HOME/cmake/*/bin
mkdir -p $ANDROID_HOME/cmake/3.22.1/bin
ln -s $PREFIX/bin/cmake $ANDROID_HOME/cmake/3.22.1/bin/cmake
ln -s $PREFIX/bin/ninja $ANDROID_HOME/cmake/3.22.1/bin/ninja

# 5. 修復 AAPT2
find ~/.gradle/caches -name "aapt2" -path "*/aapt2-*-linux/*" 2>/dev/null | while read f; do
    rm -f "$f"
    ln -s $ANDROID_HOME/build-tools/35.0.0/aapt2 "$f"
done

# 6. 複製 flutter_patched_sdk_product
FLUTTER_ROOT=$PREFIX/opt/flutter
mkdir -p $FLUTTER_ROOT/bin/cache/artifacts/engine/common/flutter_patched_sdk_product
cp -r $FLUTTER_ROOT/bin/cache/artifacts/engine/common/flutter_patched_sdk/* \
      $FLUTTER_ROOT/bin/cache/artifacts/engine/common/flutter_patched_sdk_product/

# 7. 再次構建（應該成功）
flutter build apk --release

在 Termux 中直接運行 Flutter app 並支援 hot reload：

# 1. 啟用無線調試
#    設定 → 開發者選項 → 無線調試 → 開啟

# 2. 配對設備（首次需要）
#    點擊「使用配對碼配對設備」，記下配對碼和端口
adb pair 127.0.0.1:<配對端口>
# 輸入配對碼

# 3. 連接設備
adb connect 127.0.0.1:<連接端口>

# 4. 運行 Flutter app
cd your_flutter_project
flutter run

💡 連接成功後會顯示：

Flutter run key commands.
r Hot reload. 🔥🔥🔥
R Hot restart.

方法 A：無線 ADB（同一台手機）

1. 開啟手機的「開發者選項」→「無線偵錯」
2. 點擊「使用配對碼配對裝置」，記下配對碼和端口

# 配對（只需一次）
adb pair 127.0.0.1:<配對端口>
# 輸入配對碼

# 連接
adb connect 127.0.0.1:<連接端口>

方法 B：連接其他設備

# 確保目標設備已開啟 USB 偵錯或無線偵錯
adb connect <設備IP>:5555

# 查看已連接設備
flutter devices

# 部署到 Android 設備
flutter run -d <device_id>

# 或直接安裝 APK
adb install build/app/outputs/flutter-apk/app-release.apk

⚠️ 注意：flutter devices 預設只顯示 linux。安裝 termux-android-sdk 後才會出現 Android 設備選項。

termux-flutter-wsl/
├── build.py                  # 主構建腳本
├── build.toml                # 構建配置
├── patches/                  # 引擎補丁
├── build_termux_flutter.sh   # 一鍵構建腳本 (WSL)
├── install_termux_flutter.sh # Termux 一鍵安裝腳本
├── setup_flutter_project.sh  # 專案配置腳本
├── README.md                 # 中文文檔
├── README_EN.md              # 英文文檔
├── assets/                   # 專案資源
└── .agent/workflows/         # 自動化工作流

我們在原版基礎上做了以下修正以解決 WSL 環境的兼容問題：

# build/config/termux/BUILD.gn - runtime_library
ldflags = [
  "-stdlib=libstdc++",
  "-Wl,--warn-shared-textrel",
  "-llog",   # 新增：Android 日誌庫
  "-lm",     # 新增：數學庫
]

為了支援在 Termux 上執行 flutter build apk --release（AOT 編譯），我們交叉編譯了專用的 gen_snapshot：

# 在 WSL 中構建（開發者使用）
python3 build.py configure_android --arch=arm64 --mode=release
python3 build.py build_android_gen_snapshot --arch=arm64 --mode=release

這個 gen_snapshot 的特點：

• 運行在 ARM64 Termux 上
• 產生 Android ARM64 AOT 機器碼
• 已包含 在 flutter_3.41.5_aarch64.deb 安裝包中

✅ 已驗證：gen_snapshot 在 Termux 上成功運行：

$ gen_snapshot --version
Dart SDK version: 3.11.3 on "android_arm64"

技術說明：官方 Flutter SDK 的 gen_snapshot 只能在 x86_64 Linux 上運行。我們使用 NDK 交叉編譯了一個能在 ARM64 Android (Termux) 上原生運行的版本，這是實現 flutter build apk 的關鍵。

錯誤訊息：

CMake Error: The CMAKE_C_COMPILER is not a full path to an existing compiler tool.

原因：Gradle 在構建時下載了新的 NDK 版本，但 post_install.sh 在 NDK 下載之前已經運行過，導致 clang wrapper 沒有被創建。

解決方案：重新運行 post_install.sh 來配置所有 NDK：

bash $PREFIX/share/flutter/post_install.sh
flutter build apk --release

錯誤訊息：

Unsupported file type "notFound" for libflutter_linux_gtk.so

原因：deb 包中缺少 Linux GTK 庫。

解決方案：這是構建問題，需要重新構建 deb 包並確保 flutter_gtk 目標已啟用。如果你是用戶，請下載最新版本的 deb 包。

警告訊息：

WARNING: linker: Warning: unused DT entry: DT_RPATH

原因：ELF 二進制文件包含不必要的 DT_RPATH 條目。

解決方案：這個警告不影響功能，但可以通過 termux-elf-cleaner 清除：

pkg install termux-elf-cleaner
termux-elf-cleaner $PREFIX/opt/flutter/bin/cache/dart-sdk/bin/dart

錯誤訊息：

aapt2: cannot execute: required file not found (or) EM_X86_64

原因：Gradle 下載的 aapt2 是 x86_64 版本，無法在 ARM64 上運行。

解決方案：

# 方法 1: 在 gradle.properties 中指定 ARM64 aapt2
echo "android.aapt2FromMavenOverride=$PREFIX/bin/aapt2" >> android/gradle.properties

# 方法 2: 替換 Gradle 緩存中的 aapt2
find ~/.gradle/caches -name "aapt2" -path "*aapt2-*-linux*" | while read f; do
    rm -f "$f"
    ln -s $PREFIX/bin/aapt2 "$f"
done

1. 修改 build.toml 中的 tag 為新版本號
2. 執行同步與補丁：

   python3 build.py clone
   python3 build.py sync
   python3 build.py patch_engine  # 如失敗需更新補丁文件

3. 執行完整構建流程

本專案是 mumumusuc/termux-flutter 的 Fork。要獲取上游更新：

git remote add upstream https://github.com/mumumusuc/termux-flutter.git
git fetch upstream
git merge upstream/main

注意：由於我們為 WSL 修改了部分構建腳本，合併時可能會發生衝突，請手動解決。

• mumumusuc/termux-flutter - 原始構建工具
• lzhiyong/termux-ndk - ARM64 預編譯 Android NDK
• Flutter - Google 的 UI 框架
• Termux - Android 終端模擬器

本專案基於 mumumusuc/termux-flutter，採用 GPL-3.0 協議開源。

詳見 LICENSE